<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>
      The Jena Ontology API
    </title>
    <link rev="made" href="mailto:ian.dickinson@hp.com" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <meta name="generator" content="Eclipse HTML mode" />
    <meta name="author" content="Ian Dickinson" />
    <meta name="description" content="" />
    <meta name="keywords" content="" />
    <link href="../styles/doc.css" rel="stylesheet" type="text/css" />
    <!--
      CVS: $Id: index.html,v 1.32 2009/02/24 15:15:20 ian_dickinson Exp $
     (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009 Hewlett-Packard Development Company LP
    -->
  </head>
  <body id="content">
    <h1 class="sectionHeading">
      Jena Ontology API
    </h1>

<p> In this section I will give a general introduction to the
 the Jena2 ontology API. I'll also describe a range
  of common user tasks. I won't go into all of the many details of the API here:
  you should expect to refer to the <a href="../javadoc/index.html">Jena2
  Javadoc</a> to get full details of the capabilities of the API.
      Feedback, (via the <a href="http://tech.groups.yahoo.com/group/jena-dev">jena-dev</a> support list) is welcomed.
    </p>
    <h2>
      Prerequisites
    </h2>

<p> I will assume that you have a basic familiarity with RDF and with Jena.
  There are many other Jena <a href="../documentation.html">help documents</a> you can read for background
  on these topics. There is also a <a href="../tutorial/index.html">Jena programming
  tutorial</a> you can follow through.</p>
  <p>Jena is a programming toolkit, using the Java programming language. While there
  are a few command-line tools to help you perform some key tasks using Jena, mostly
  you use Jena by writing Java programs. The examples in this document will be primarily
  code samples.</p>
  <p>I also won't be explaining the OWL or RDFS ontology languages in much detail
  in this document. You should expect
  to refer to supporting documentation for details on those languages, for example
  the <a href="http://www.w3.org/2004/OWL/">W3C OWL document index</a>.</p>
  <p><strong>Note:</strong> At the time of writing, work on OWL version 1.1 is still underway.
  No decision has yet been made about when Jena will support the new OWL 1.1 features. I will
  only use OWL 1.0 features in this document.</p>

    <h2>Overview</h2>
    <p>
      The section of the manual is broken into a number of sections. You do not need to
      read them in sequence, though later sections may refer to concepts and techniques
      introduced in earlier sections. The sections are:
    </p>

    <ol>
      <li> Overview </li>
        <li><a href="#generalConcepts">General concepts</a></li>
        <li><a href="#eswcExample">Running example: the ESWC ontology</a></li>
        <li><a href="#creatingModels">Creating ontology models</a></li>
        <li><a href="#documentHandling">Compound ontology documents and imports processing</a></li>
        <li><a href="#ontResource">The generic ontology type: OntResource</a></li>
        <li><a href="#classesBasic">Ontology classes and basic class expressions</a></li>
        <li><a href="#properties">Ontology properties</a></li>
        <li><a href="#classesComplex">More complex class expressions</a></li>
        <li><a href="#instances">Instances or individuals</a></li>
        <li><a href="#metadata">Ontology meta-data</a></li>
        <li><a href="#inferenceIntro"> Ontology inference: overview</a></li>
        <li><a href="#legacyDAML">Working with DAML+OIL ontologies</a></li>
        <li><a href="#persistence">Working with persistent ontologies</a></li>
        <li><a href="#ontTools">Experimental ontology tools</a></li>
        <li><a href="common-problems.html">Common ontology application problems and sample programs</a></li>
    </ol>

    <h3>
      Further assistance
    </h3>
    <p>
      I hope that this document will be sufficient to help most readers to get started
      using the Jena ontology API. For further support, please post questions to the
      Jena support list: <a href="http://tech.groups.yahoo.com/group/jena-dev">jena-dev@yahoogroups</a>.
      You can also report bugs directly into the <a href="https://sourceforge.net/tracker/?atid=430288&amp;group_id=40417&amp;func=browse">Jena bug tracker</a> on
      <a href="http://sourceforge.net/projects/jena">SourceForge</a>.
    </p>
    <p><em>
      Please note that we ask that you use the support list or the bug-tracker to
      communicate with the Jena team, rather than send email to the team members directly.
      This helps us manage Jena support more effectively, and facilitates contributions
      from other Jena community members.</em>
    </p>
    <h2 id="generalConcepts">General concepts</h2>
    <p>
      In a widely-quoted definition, an ontology is
    </p>
    <blockquote>
      <p>
        "&#133; a specification of a conceptualization" [<a href="http://www-ksl.stanford.edu/kst/what-is-an-ontology.html">Gruber, T.</a> 1993]
      </p>
    </blockquote>
        <p>Let's unpack that brief characterisation a bit. It means
    that an ontology allows a programmer to specify, in an open, meaningful,
    way the concepts and relationships that collectively characterise some
    domain. Examples might be the concepts of red and white wine, grape
    varieties, vintage years, wineries and so forth that characterise the
    domain of 'wine', and relationships such as 'wineries produce wines',
    'wines have a year of production'. This <em>wine ontology</em> might be
    developed initially for a particular application, such as a
    stock-control system at a wine warehouse. As such, it may be considered
    similar to a well-defined database schema. The advantage to an ontology
    is that it is an explicit, first-class description. So having been
    developed for one purpose, it can be published and reused for other
    purposes. For example, a given winery may use the wine ontology to link
    its production schedule to the stock system at the wine warehouse.
    Alternatively, a wine recommendation program may use the wine ontology,
    and a description (ontology) of different dishes to recommend wines for
    a given menu.</p>
        <p>There are many ways of writing down an ontology, and a variety of
    opinions as to what kinds of definition should go in one. In practice,
    the contents of an ontology are largely driven by the kinds of
    application it will be used to support. In Jena, we do not take a
    particular view on the minimal or necessary components of an ontology.
    Rather, we try to support a variety of common techniques. In this manual
    I try to explain what is &#150; and to some extent what isn't &#150;
    possible using Jena's ontology support.</p>
        <p>Since Jena is fundamentally an RDF platform, Jena's ontology support
        is limited
    to ontology formalisms built on top of RDF. Specifically this means
    <a href="http://en.wikipedia.org/wiki/RDFS">RDFS</a>,
    the varieties of <a href="http://en.wikipedia.org/wiki/Web_Ontology_Language">OWL</a>,
    and the now-obsolete
    <a href="http://en.wikipedia.org/wiki/DAML%2BOIL">DAML+OIL</a>. I will provide a very brief
    introduction to these languages here. Please refer to the
    extensive on-line documentation for these formalisms for complete and
    authoritative detail.</p>
    <h3>
      RDFS
    </h3>
        <p>RDFS is the weakest ontology language supported by Jena. RDFS
    allows the ontologist to build a simple hierarchy of concepts, and a
    hierarchy of properties. Consider the following trivial characterisation
    (with apologies to biology-trained readers!):</p>
    <p class="centered">
      <img src="../images/Simple-hierarchy.png" width="372" height="210" alt="image of simple class hierarchy" />
    </p>
    <p class="caption">
      Table 1: A simple concept hierarchy
    </p>
        <p>Using RDFS, I can say that my ontology has five <em>classes</em>,
    and that <code>Plant</code> is a <em>sub-class of</em> <code>Organism</code> and
    so on. So every animal is also an organism. A good way to think of these
    classes is as describing sets of <em>individuals</em>: organism is
    intended to describe a set of living things, some of which are animals
    (i.e. a sub-set of the set of organisms is the set of animals), and some
    animals are fish (a subset of the set of all animals is the set of all
    fish).</p>
        <p>To describe the attributes of these classes, I can associate <em>properties</em>
    with the classes. For example, animals have sensory organs (noses,
    eyes, etc.). A general property of an animal might be <code>senseOrgan</code>, to
    denote any given sensory organs a particular animal has. In general,
    fish have eyes, so a fish might have a <code>eyes</code> property to
    refer to a description of the particular eye structure of some species.
    Since eyes are
    a type of sensory organ, we can capture this relationship between these
    properties by saying that <code>eye</code> is a sub-property-of <code>senseOrgan</code>.
    Thus if a given fish has two eyes, it also has two sense organs. (It may
    have more, but we know that it must have two).
    </p>
        <p>I can describe this simple hierarchy with RDFS. In general,
    the class hierarchy is a graph rather than a tree (i.e. not like Java class inheritance).
    The <a href="http://en.wikipedia.org/wiki/Slime_mold">slime mold</a> is
    popularly, though perhaps not accurately, thought of as an organism
    that has characteristics of both plants and animals. I might model
    a slime mold in my ontology as a class that has
    both plant and animal classes among
    its super-classes. RDFS is too weak a language to express that a thing
    cannot be both a
    plant and an animal (which is perhaps lucky for the slime molds). In RDFS,
    I can only
    name the classes, I cannot construct expressions to describe
    interesting classes. However, for many applications it is sufficient to
    state the basic vocabulary, and RDFS is perfectly well suited to this.</p>
    <p>Note also that I can both describe classes, in general terms, and
    I can describe particular <em>instances</em>
    of those classes. So there may be a particular individual Fred who is a
    Fish (i.e. has <code>rdf:type Fish</code>), and who has two eyes. His
    companion Freda, a <a href="http://en.wikipedia.org/wiki/Mexican_tetra">
    Mexican Tetra</a>, or blind cave fish, has no eyes. One
    use of an ontology is to allow us to fill-in missing information about
    individuals. Thus, though it is not stated directly, we can deduce that Fred
    is also an Animal and an Organism. Assume that there was no <code>rdf:type</code>
    asserting that Freda is a Fish. We may still infer Freda's <code>rdf:type</code>
    since Freda has <a href="http://en.wikipedia.org/wiki/Lateral_line">lateral lines</a>
    as sense organs, and these only occur in fish. In RDFS, we state that the
    <em>domain</em> of the <code>lateralLines</code> property is the <code>Fish</code>
    class, so an RDFS reasoner can infer that Freda must be a fish.</p>
    <h3>OWL</h3>
        <p>In general, OWL allows me to say everything that RDFS allows, and
    much more besides. A key part of OWL is the ability to describe classes
    in more interesting and complex ways. For example, in OWL we can say
    that Plant and Animal are <em>disjoint classes</em>: no individual can
    be both a plant and an animal (which would have the unfortunate
    consequence of making <code>SlimeMold</code> an empty
    class). <code>SaltwaterFish</code> might be the <em>intersection</em> of
    <code>Fish</code> and
    the class <code>SeaDwellers</code> (which also includes, for example, cetaceans and
    sea plants).</p>
        <p>Suppose I have a property <code>covering</code>, intended to
    represent the scales of a fish or the fur of a mammal. I can now refine
    the mammal class to be 'animals that have a covering that is hair',
    using a <em>property restriction</em> to express the condition that
    property <code>covering</code> has a value from the class <code>Hair</code>.
    Similarly <code>TropicalFish</code> might be the intersection of the
    class of <code>Fish</code> and the class of things that have <code>TropicalOcean</code>
    as their habitat.</p>
        <p>Finally (for this brief overview), I can say more about
    properties in OWL. In RDFS, properties can be related via a property
    hierarchy. OWL extends this by allowing properties to be denoted as <em>transitive</em>,
    <em>symmetric</em> or <em>functional</em>, and allow one property to be
    declared to be the <em>inverse</em> of another. OWL also makes a
    distinction between properties that have data-values (known as <em>literals</em>
    in RDF terminology) as their range, or other individuals. Respectively
    these are <em>datatype properties</em> and <em>object properties</em>.
    A consequence
    of the RDF lineage of OWL is that OWL ontologies cannot make statements
    about literal values. I cannot say in RDF that 7 has the property of
    being a prime number. I can, of course, say that the class of primes includes
    7, but that doesn't require a number to be the subject of an RDF statement.
    In OWL, this distinction is important since only
    object properties can be transitive or symmetric.</p>
    <p> The OWL language is sub-divided into three syntax classes: <em>OWL Lite</em>,
      <em>OWL DL</em> and <em>OWL Full</em>. OWL DL does not permit some
      constructions allowed in OWL Full, and OWL Lite has all the constraints
      of OWL DL plus some more. The
      intent for OWL Lite and OWL DL is to make the task of reasoning with
      expressions in that subset more tractable. Specifically, OWL DL is
      intended to be able to be processed efficiently by a
      <a href="http://en.wikipedia.org/wiki/Description_logic"><em>description
      logic</em></a> reasoner. OWL Lite is intended to be amenable to processing
      by a variety of reasonably simple inference algorithms, though experts
      in the field have challenged how successfully this has been achieved. </p>
        <p>While the OWL standards documents note that OWL builds on top of
    the (revised) RDF specifications, it is possible to treat OWL as a
    separate language in its own right, and not something that is built on
    an RDF foundation. This view uses RDF as a serialisation syntax; the
    RDF-centric view treats RDF triples as the core of the OWL formalism.
    While both views are valid, in Jena we take the RDF-centric view.</p>

      <h3>DAML+OIL</h3>
      <p>DAML+OIL is very similar to OWL Full. This is not surprising,
      since the W3C's Web Ontology Working Group, who designed OWL, took
      DAML+OIL as their starting point. Some constructions in OWL have been
      added to the capabilities of DAML+OIL, and one or two have been removed.
      For the purposes of this brief overview, however, the expressiveness of
      DAML+OIL is comparable to that of OWL.</p><p><strong>Note:</strong> DAML+OIL is effectively now
      obsolete. While you can still find some DAML ontologies on the web, you
      should work with OWL or RDFS to maximise the longevity of your models.</p>

    <h3>Ontology languages and the Jena Ontology API</h3>
    <p>
      As I outlined above, there are various different ontology languages available
      for representing ontology
      information on the semantic web. They range from the most expressive, OWL
      Full, through to the weakest, RDFS. Through the Ontology API, Jena aims to
      provide a consistent programming interface for ontology application
      development, independent of which ontology language you are using in your programs.
    </p>
    <p>
      The Jena Ontology API
      is language-neutral: the Java class names do not mention the underlying language.
      For example, the <code>OntClass</code> Java class can represent an OWL class,
      RDFS class, or DAML class.
      To represent the differences between the various representations,
      each of the ontology languages has a <em>profile</em>, which lists the permitted constructs
      and the names of the classes and properties. Thus in the DAML profile, the URI for object
      property is <code>daml:ObjectProperty</code>
      (short for <code>http://www.daml.org/2001/03/daml+oil#ObjectProperty</code>),
      in the OWL profile is it <code>owl:ObjectProperty</code>
      (short for <code>http://www.w3.org/2002/07/owl#ObjectProperty</code>)
      and in the RDFS profile it is <code>null</code> since RDFS does not define object properties.
    </p>
    <p>
      The profile is bound to an <em>ontology model</em>, which is an extended version of Jena's
      <a href="../javadoc/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a>
      class.
      The base <code>Model</code> allows access to the statements in a collection of RDF data.
      <a href="../javadoc/com/hp/hpl/jena/ontology/OntModel.html"><code>OntModel</code></a>
      extends
      this by adding support for the kinds of objects expected to be in an ontology: classes (in
      a class hierarchy), properties (in a property hierarchy) and individuals. When you're
      working with an ontology in Jena, all of the state information remains encoded as RDF
      triples (which Jena calls <code>Statement</code>s) stored in the RDF model. The ontology
      API <em>doesn't change the RDF representation of ontologies</em>. What it does do is add
      a set of convenience classes and methods that make it easier for you to write programs that
      manipulate the RDF statements.</p>
      <p>The predicate names
      defined in the ontology language correspond to the accessor methods on the Java classes
      in the API. For example, an <code>OntClass</code>
      has a method to list its super-classes, which corresponds to the values of the <code>subClassOf</code>
      property in the RDF representation. This point is worth re-emphasising: no
      information is stored in the <code>OntClass</code> object itself.
      When you call the OntClass <code>listSuperClasses()</code> method, Jena will retrieve the information
      from the underlying RDF statements. Similarly adding a subclass to an <code>OntClass</code>
      asserts an additional RDF statement into the model.
    </p>

    <h3>Ontologies and reasoning</h3>
    <p>One of the main reasons for building an ontology-based application is to use
    a reasoner to derive additional truths about the concepts you are modelling. We
    saw a simple instance of this above: the assertion &quot;Fred is a Fish&quot; <em>entails</em>
    the deduction &quot;Fred is an Animal&quot;. There are many different styles of automated
    reasoner, and very many different reasoning algorithms. Jena includes support
    for a variety of reasoners through the
    <a href="../inference/index.html">inference API</a>. A common feature of Jena
    reasoners is that they create a new RDF model which appears to contain the triples
    that are derived from reasoning, as well as the triples that were asserted in
    the base model. This extended model is, nevertheless, still conforms to the contract
    for Jena models. So it can be used wherever a base model can be used. The ontology
    API exploits this feature: the convenience methods the ontology API provides can
    query an extended inference model in just the same way as a plain RDF model. In fact,
    this is such a common pattern that we provide simple recipes for constructing
    ontology models whose language, storage model and reasoning engine can all be
    simply specified when an <code>OntModel</code> is created. I'll show examples later.</p>
        <p>Figure 2 shows one way of visualising this:</p>
    <p class="centered">
      <img src="../images/Ont-model-layers.png" width="312" height="285" alt="image of layering of graphs in model" />
    </p>
    <p class="centered">Figure 2: the statements seen by the OntModel</p>
    <p><code>Graph</code> is an internal Jena interface that supports the composition
    of sets of RDF triples. The asserted statements, which may have been read in
    from an ontology document, are held in the base graph.
    The reasoner, or
    inference engine, can use the contents of the base graph and the
    semantic rules of the language to show a more complete set of
    statements. This is also presented via a <code>Graph</code> interface,
    so the model works only with the outermost interface.
    This regularity allows us to very easily build
    ontology models with or without a reasoner. It also means that the
    base graph can be an in-memory store, a database-backed persistent
    store, or some other storage structure altogether (e.g. an LDAP
    directory) again without affecting the operation of the ontology model.</p>
    <h3 id="rdfPolymorphism">RDF-level polymorphism and Java</h3>
    <p>
      Deciding which Java abstract class to use to represent a given RDF resource
      can be surprisingly subtle. Consider the following RDF sample:
    </p>
<pre class="codesample">&lt;owl:Class rdf:ID=&quot;DigitalCamera&quot;&gt;
&lt;/owl:Class&gt;</pre>
      <p>This declares that the resource with the relative URI
  <code>#DigitalCamera</code> is an OWL ontology class. It suggests that it
  would be appropriate to model
  that declaration in Java with an instance of an <code>OntClass</code>. Now
  suppose I add a triple to the RDF model to augment the class
  declaration with some more information:</p>
<pre class="codesample">&lt;owl:Class rdf:ID=&quot;DigitalCamera&quot;&gt;
  &lt;rdf:type owl:Restriction /&gt;
&lt;/owl:Class&gt;</pre>
    <p>Now I am saying that <code>#DigitalCamera</code> is an OWL
    Restriction. Restriction is a subclass of <code>owl:Class</code>, so this is a perfectly
    consistent operation. The problem I have is that Java does not allow
    me to dynamically change the Java class of the object representing this
    resource. The resource has not changed: it still has URI <code>#DigitalCamera</code>.
    But the appropriate Java class Jena might choose to model it has changed
    from <code>OntClass</code> to <code>Restriction</code>. Conversely, if
    I subsequently remove the <code>rdf:type&nbsp;owl:Restriction</code> from the model, using the
    <code>Restriction</code> Java class is no longer appropriate.</p>
<p>
      Even worse, OWL Full allows me to state the following (rather counter-intuitive) construction:
    </p>
<pre class="codesample">&lt;owl:Class rdf:ID=&quot;DigitalCamera&quot;&gt;
  &lt;rdf:type owl:ObjectProperty /&gt;
&lt;/owl:Class&gt;</pre>
    <p>That is, <code>#DigitalCamera</code> is both a class <em>and</em>
    a property. While this may not be a very useful operation, it
    illustrates a basic point: we cannot rely on a consistent or unique
    mapping between an RDF resource and the appropriate Java abstraction.</p>
        <p>Jena accepts this basic characteristic of polymorphism at the
    RDF level by considering that the Java abstraction (<code>OntClass</code>,
    <code>Restriction</code>, <code>DatatypeProperty</code>, etc.) is just a view or <em>facet</em> of
    the resource. That is, there is a one-to-many mapping from a resource to
    the facets that the resource can present. If the resource is typed as
    an <code>owl:Class</code>, it can present the <code>OntClass</code> facet;
    given other types, it can present other facets. Jena provides the
    <code>.as()</code> method to efficiently map from an RDF object to one of
    its allowable facets.
    Given a RDF object (i.e. an instance of <code>com.hp.hpl.jena.rdf.model.RDFNode</code>
    or one of its sub-types), I can get a facet by invoking <code>as()</code>
    with an argument that denotes the facet required. Specifically, the facet is
    identified by the Java class object of the desired facet. For example, to
    get the <code>OntClass</code> facet of a resource, I can do:</p>
<pre class="codesample">Resource r = myModel.getResource( myNS + &quot;DigitalCamera&quot; );
OntClass cls = (OntClass) r.as( OntClass.class );</pre>
        <p>This pattern allows me to defer decisions about
    the correct Java abstraction to use until run-time. The choice can depend on the
    properties of the resource itself. If a given RDFNode will not support
    the conversion to a given facet, it will raise a <code>ConversionException</code>.
    I can test if <code>.as()</code> will succeed for a given facet with
    <code>canAs()</code>. This RDF-level polymorphism is used extensively in
    the Jena ontology API to allow maximum flexibility in handling ontology data.
    </p>

    <h2 id="eswcExample">Running example: the ESWC ontology</h2>

<p> To illustrate the principles of using the ontology API, I will use examples drawn
  from Tom Heath's
    <a href="http://www.schemaweb.info/schema/SchemaDetails.aspx?id=282">ESWC ontology</a>.
    This ontology presents a simple model for describing the concepts and activities
    associated with a typical academic conference.
   A copy of the ontology serialized in RDF/XML is included with the Jena
  download, see: [<a href="../../src-examples/data/eswc-2006-09-21.rdf"><code>eswc-2006-09-21.rdf</code></a>]
  (note that you may need to view the page source in some browsers to see the XML code). </p>
    <p>
      A subset of the classes and properties from the ontology are shown in Figure 3:
    </p>
    <p class="centered">
      <img src="../images/eswc-classes.png" style="width:589px;height:487px" alt="Image of the example class hierarchy" />
    </p>
    <p class="caption">
      Figure 3: Classes and properties from ESWC ontology
    </p>
    <p>
      I will use elements from this ontology to illustrate the ontology API throughout
      the rest of this document.
    </p>

    <h2 id="creatingModels">Creating ontology models</h2>

  <p> An ontology model is an extension of the Jena RDF model that provides extra
    capabilities for handling ontologies. Ontology models are created
    through the Jena <a href="../javadoc/com/hp/hpl/jena/rdf/model/ModelFactory.html"><code>ModelFactory</code></a>.
    The simplest way to create an ontology model is as follows: </p>
<pre class="codesample">OntModel m = ModelFactory.createOntologyModel();</pre>
    <p>This will create an ontology model with the <em>default</em> settings, which
    are set for maximum compatibility with the previous version of Jena. These defaults
    are:</p>
    <ul>
    <li>OWL-Full language</li>
    <li>in-memory storage</li>
    <li>RDFS inference, which principally produces entailments from the
      sub-class and sub-property hierarchies.</li>
    </ul>
    <p>In many applications, such as driving a GUI, RDFS inference is too strong (for example, every
    class is inferred to be a sub-class of <code>owl:Thing</code>. In other applications, stronger
    reasoning is needed. In general, to create an <code>OntModel</code> with a particular reasoner
    or language profile, you should pass a model specification to the <code>createOntologyModel</code>
    call. For example, an OWL model that performs no reasoning at all can be created with:</p>
<pre class="codesample">OntModel m = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM );</pre>
        <p>To create an ontology model for a particular language, but
    leaving all of the other values as defaults, you should pass the URI of the
    ontology language to the model factory. The URI strings for the various
    language profiles are:</p>
    <table class="definitions" summary="ontology languague URIs">
      <tr>
        <th class="def1a">
          Ontology language
        </th>
        <th class="def1b">
          URI
        </th>
      </tr>
      <tr>
        <td>RDFS</td>
        <td>
            <code>http://www.w3.org/2000/01/rdf-schema#</code>
        </td>
      </tr>
      <tr>
        <td>DAML+OIL</td>
        <td>
            <code>http://www.daml.org/2001/03/daml+oil#</code>
        </td>
      </tr>
      <tr>
        <td>OWL Full</td>
        <td>
            <code>http://www.w3.org/2002/07/owl#</code>
        </td>
      </tr>
      <tr>
        <td>OWL DL</td>
        <td>
            <code>http://www.w3.org/TR/owl-features/#term_OWLDL</code>
        </td>
      </tr>
      <tr>
        <td>OWL Lite</td>
        <td>
          <code>http://www.w3.org/TR/owl-features/#term_OWLLite</code>
        </td>
      </tr>
    </table>

  <p> These URI's are used to look-up the language profile from the
  <a href="../javadoc/com/hp/hpl/jena/ontology/ProfileRegistry.html"><code>ProfileRegistry</code></a>.
  Fortunately, the profile registry contains declared constants so that you do
  not have to remember these URI's. Please note that the URI's denoting OWL Lite
  and OWL DL are not officially sanctioned by the OWL standard. </p>
    <p>
      To create an ontology model for handling DAML ontologies, use either of:
    </p>
<pre class="codesample">OntModel m = ModelFactory.createOntologyModel( OntModelSpec.DAML_MEM );
OntModel m = ModelFactory.createOntologyModel( ProfileRegistry.DAML_LANG );</pre>

<p> Beyond these basic choices, the complexities of configuring an ontology model
  are wrapped up in a recipe object called
  <code><a href="../javadoc/com/hp/hpl/jena/ontology/OntModelSpec.html">OntModelSpec</a></code>.
  This specification allows complete control over the configuration choices for the ontology
  model, including the language profile in use, the reasoner, and the means of
  handling compound documents. A number of common recipes are
  pre-declared as constants in <code>OntModelSpec</code>, and listed below.</p>

      <table id="ontModelSpecs" class="definitions" summary="pre-defined OntModel specifications">
      <tr><th style="width:100px">OntModelSpec</th><th style="width:100px">Language profile</th><th style="width:100px">Storage model</th><th style="width:350px">Reasoner</th></tr>
      <tr><td class="codesample">OWL_MEM</td><td>OWL full</td><td>in-memory</td><td>none</td></tr>
      <tr><td class="codesample">OWL_MEM_TRANS_INF</td><td>OWL full</td><td>in-memory</td><td>transitive class-hierarchy inference</td></tr>
      <tr><td class="codesample">OWL_MEM_RULE_INF</td><td>OWL full</td><td>in-memory</td><td>rule-based reasoner with OWL rules</td></tr>
      <tr><td class="codesample">OWL_MEM_MICRO_RULE_INF</td><td>OWL full</td><td>in-memory</td><td>optimised rule-based reasoner with OWL rules</td></tr>
      <tr><td class="codesample">OWL_MEM_MINI_RULE_INF</td><td>OWL full</td><td>in-memory</td><td>rule-based reasoner with subset of OWL rules</td></tr>
      <tr><td class="codesample">OWL_DL_MEM</td><td>OWL DL</td><td>in-memory</td><td>none</td></tr>
      <tr><td class="codesample">OWL_DL_MEM_RDFS_INF</td><td>OWL DL</td><td>in-memory</td><td>rule reasoner with RDFS-level entailment-rules</td></tr>
      <tr><td class="codesample">OWL_DL_MEM_TRANS_INF</td><td>OWL DL</td><td>in-memory</td><td>transitive class-hierarchy  inference</td></tr>
      <tr><td class="codesample">OWL_DL_MEM_RULE_INF</td><td>OWL DL</td><td>in-memory</td><td>rule-based reasoner with OWL rules</td></tr>
      <tr><td class="codesample">OWL_LITE_MEM</td><td>OWL Lite</td><td>in-memory</td><td>none</td></tr>
      <tr><td class="codesample">OWL_LITE_MEM_TRANS_INF</td><td>OWL Lite</td><td>in-memory</td><td>transitive class-hierarchy inference</td></tr>
      <tr><td class="codesample">OWL_LITE_MEM_RDFS_INF</td><td>OWL Lite</td><td>in-memory</td><td>rule reasoner with RDFS-level entailment-rules</td></tr>
      <tr><td class="codesample">OWL_LITE_MEM_RULES_INF</td><td>OWL Lite</td><td>in-memory</td><td>rule-based reasoner with OWL rules</td></tr>
      <tr><td class="codesample">DAML_MEM</td><td>DAML+OIL</td><td>in-memory</td><td>none</td></tr>
      <tr><td class="codesample">DAML_MEM_TRANS_INF</td><td>DAML+OIL</td><td>in-memory</td><td>transitive class-hierarchy inference</td></tr>
      <tr><td class="codesample">DAML_MEM_RDFS_INF</td><td>DAML+OIL</td><td>in-memory</td><td>rule reasoner with RDFS-level entailment-rules</td></tr>
      <tr><td class="codesample">DAML_MEM_RULE_INF</td><td>DAML+OIL</td><td>in-memory</td><td>rule-based reasoner with DAML rules</td></tr>
      <tr><td class="codesample">RDFS_MEM</td><td>RDFS</td><td>in-memory</td><td>none</td></tr>
      <tr><td class="codesample">RDFS_MEM_TRANS_INF</td><td>RDFS</td><td>in-memory</td><td>transitive class-hierarchy inference</td></tr>
      <tr><td class="codesample">RDFS_MEM_RDFS_INF</td><td>RDFS</td><td>in-memory</td><td>rule reasoner with RDFS-level entailment-rules</td></tr>
      </table>


<p>For details of reasoner capabilities, please see the <a href="../inference/index.html">inference
  documentation</a> and the Javadoc for <a href="../javadoc/com/hp/hpl/jena/ontology/OntModelSpec.html">OntModelSpec</a>.
  See also further discussion <a href="#inferenceIntro">below</a>.
  </p>

<p> <strong>Note:</strong> it is primarily the choice of reasoner, rather than the choice of language
  profile, that determines which entailments are seen by the ontology model. However,
  using an OWL reasoner with DAML source data will result in few additional entailments
  being seen by the ontology model. </p>

<p> To create a model with a given specification, you should invoke the <code>ModelFactory</code>
  as follows: </p>
<pre class="codesample">OntModel m = ModelFactory.createOntologyModel( <em>&lt;model spec&gt;</em> );</pre>
    <p>for example:</p>
<pre class="codesample">OntModel m = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM_MICRO_RULE_INF );</pre>
    <p>To create a custom model specification, you can create a new one
from its constructor, and call the various setter methods to set the appropriate values.
More often, you want a variation on an existing recipe. In this
case, you copy an existing specification and then update the copy as
necessary:</p>
<pre class="codesample">OntModelSpec s = new OntModelSpec( OntModelSpec.OWL_MEM );
s.setDocumentManager( myDocMgr );
OntModel m = ModelFactory.createOntologyModel( s );</pre>

    <h2 id="documentHandling">Compound ontology documents and imports processing</h2>

    <p>The OWL and DAML ontology languages include some facilities for creating modular
    ontologies that can be re-used in a similar manner to software modules. In particular,
    one ontology can <em>import</em> another. Jena helps ontology developers to work
    with modular ontologies by automatically handling the imports statements in
    ontology models.</p>
    <p>The key idea is that the base model of an ontology model is actually a collection
    of models, one per imported model. That means we have to modify figure 2 a bit.
    Figure 4 shows how the ontology model builds a collection of import models:</p>
    <p class="centered">
      <img src="../images/Ont-model-layers-import.png" width="563" height="331" alt="Diagram of compound document for imports" />
    </p>
    <p class="caption">Figure 4: ontology model compound document structure for imports</p>

  <p>I will use the term <em>document</em> to describe an ontology serialized in some
    transport syntax, such as RDF/XML or N3. This terminology isn't used by the OWL
    or RDFS standards, but it is a convenient way to refer to the written artifacts.
    However, from a broad view of the interlinked semantic web, a document view imposes
    artificial boundaries between regions of the global web of data.</p>
    <p>We will load an ontology document into an
    ontology model in the same way as a normal Jena model, using the <code>read</code>
    method. There are several variants on read, that handle differences in the source
    of the document (to be read from a resolvable URL or directly from an input
    stream or reader), the base URI that will resolve any relative URI's in the
    source document, and the serialisation language. In summary, these variants
    are: </p>
<pre class="codesample">read( String url )
read( Reader reader, String base )
read( InputStream reader, String base )
read( String url, String lang )
read( Reader reader, String base, String Lang )
read( InputStream reader, String base, String Lang )</pre>
      <p>You can use any of these methods to load an ontology document.
  Note that we advise that you avoid the the <code>read()</code> variants that
  accept  a  <code>java.io.Reader</code> argument
  when loading XML documents containing internationalised
  character sets, since the handling of character encoding by the Reader
  and by XML parsers is not compatible.
  </p>
      <p>By default, when an ontology model reads an ontology document, it
      will also locate and load the document's imports. An OWL or DAML document
  may contain an individual of class <code>Ontology</code>, which contains meta-data
  about that document itself. For example:</p>
<pre class="codesample">&lt;owl:Ontology rdf:about=""&gt;
  &lt;dc:creator rdf:value="Ian Dickinson" /&gt;
  &lt;owl:imports rdf:resource="http://jena.hpl.hp.com/example-ont" /&gt;
&lt;/owl:Ontology&gt;</pre>
    <p>The construct <code>rdf:about=&quot;&quot;</code> is a relative URI that
      will resolve to the document's base URI: in other words it's a shorthand
      way of referring to the document itself. The <code>owl:imports</code> line
       states that this ontology is
      constructed using classes, properties and individuals from the referenced
      ontology. When <code>OntModel</code> reads this document, it will notice
      the <code>owl:imports</code> line and attempt to load the imported ontology
      into a sub-model of the ontology model being built. The definitions from both the
      base ontology and all of the imports will be visible to the reasoner.</p>

    <p>Each imported ontology document is held in a separate graph structure.
      This is important: I want to keep the original source ontology separate
      from the imports. When I write the model out again, normally only the base
      model is written (the alternative is that all you see is a confusing union
      of everything). And when I update the model, only the base model changes.
    </p>
        <p>Imports are processed recursively, so if my base document
    imports ontology A, and A imports B, I will end up with the structure
    shown in Figure 4. Note that the imports have been flattened out.
    A cycle check is used to prevent the document
    handler getting stuck if, for example, A imports B which imports A!</p>

    <h3>The ontology document manager</h3>
    <p>
      Each ontology model has an associated <em>document manager</em> that assists with
      the processing and handling of documents-related concerns. For convenience,
      there is one global document manager that is used by default by ontology
      models. You  can get a reference to this shared instance through
      <code>OntDocumentManager.getInstance()</code>. In many cases,
      it will be sufficient to simply change the settings on the global
      document manager to suit your application's needs. However, for
      more fine-grain control, you can create
      separate document managers,  and pass them
      to the ontology model when it is created through the model factory.
      To do this, create an ontology specification object (see above),
      and set the document manager. For example:
    </p>
<pre class="codesample">OntDocumentManager mgr = new OntDocumentManager();
// set the mgr's properties now
 &#133; some code &#133;
// now use it
OntModelSpec s = new OntModelSpec( OntModelSpec.RDFS_MEM );
s.setDocumentManager( mgr );
OntModel m = ModelFactory.createOntologyModel( s );</pre>
        <p>Note that the model retains a reference to the document manager
    it was created with. Thus if you change a document manager's properties,
    it will
    affect models that have previously been constructed with that document
    manager.</p>

    <h3>Document manager policy</h3>
        <p>Since the document manager has a large number of configurable
    options, there are two ways in which you can customise it to your
    application
    requirements. Firstly, you can set the individual parameters of the document manager
    by Java code. Alternatively, when a given document manager is
    created it can load values for the various parameters from a policy
    file, expressed in RDF. The document manager has a list of URL's
    which it will search for a policy document. It will stop at the first
    entry on the list that resolves to a retrievable document. The default
    search path for the policy is: <code>file:./etc/ont-policy.rdf;file:ont-policy.rdf</code>.
    You can find the default policy, which can serve as a template for defining
    your own policies, in the <code>etc/</code> directory under the
    Jena download directory.</p>
    <p>
      You can set the general properties of the document manager in the policy as follows:
    </p>
<pre class="codesample">&lt;DocumentManagerPolicy&gt;
  &lt;!-- policy for controlling the document manager's behaviour --&gt;
  &lt;processImports rdf:datatype="&amp;xsd;boolean"&gt;true&lt;/processImports&gt;
  &lt;cacheModels rdf:datatype="&amp;xsd;boolean"&gt;true&lt;/cacheModels&gt;
&lt;/DocumentManagerPolicy&gt;</pre>

    <p>
      You can find the simple schema that declares the various properties that you can use in
      such an ontology document policy in the vocabularies directory of the Jena download. It's called <code>ont-manager.rdf</code>. To change the search path that
      the document manager will use to initialise itself, you can either pass the new
      search path as a string when creating a new document manager object, or
      call the method <code>setMetadataSearchPath()</code>.</p>

    <h3>The ModelMaker: creating storage on demand</h3>

  <p> In order for the document manager to build the union of the imported documents
    (which we may refer to as the <em>imports closure</em>), there must be some means of creating
    new graphs to store the imported ontologies. Loading a new import means that there
    needs to be a new graph added
    Jena defines a <em>model maker</em> as a simple interface that allows
    different kinds of model storage (in memory, file-backed, in a persistent database, etc.)
    to be created  on demand. For the database case, this may include passing the database
    user-name and password and other connection parameters. New model makers can
        be created with the <code><a href="../javadoc/com/hp/hpl/jena/rdf/model/ModelFactory.html">ModelFactory</a></code>.</p>
    <p>There are two cases in which we may want to create storage for
    models on-demand. The first is when creating the <code>OntModel</code>
    for the first time, some variants of <code>createOntologyModel</code>
    will allocate space for the <em>base model</em> (instead of, for
    example, being handed a base model to use as one of the method
    arguments). The second case when storage must be allocated is when
    adding an imported document to the union of imports. These cases often
    require different policies, so the <code>OntModelSpec</code> contains
    two model maker parameters: the <em>base model maker</em> and <em>imports
    model maker</em>, available via <code>getBaseModelMaker()</code> and <code>getImportsModelMaker()</code>
    methods respectively.</p>

    <p>The default specifications in OntModelSpec that begin MEM_ use an
    in-memory model maker for the both the base model and the imported
    documents.</p>
    <p><strong>Implementation note</strong>: internally to Jena, we use
    <code>Graph</code> as a primary data structure. However, your code will
    almost always refer to models, not graphs. What's happening is that a <code>Model</code>
    is a wrapper around the <code>Graph</code>, which balances a rich,
    convenient programming interface (<code>Model</code>) with a simple,
    manageable internal data structure (<code>Graph</code>). Hence some
    potential confusion in that Figure 4, above, refers to a structure
    containing graphs, but we use a <code><a
      href="../javadoc/com/hp/hpl/jena/rdf/model/ModelMaker.html"
    >ModelMaker</a></code> to generate new stores. The document manager extracts the
    appropriate graph from the containing model. Except in cases where you
    are extending Jena's internal structures, you should think of <code>Model</code>
    as the container of RDF and ontology data.</p>

<h3>Controlling imports processing</h3>

        <p>Normally, loading imports during the <code>read()</code> call
    automatic. To <code>read()</code> an ontology without building the imports closure, call
    the method <code>setProcessImports(&nbsp;false&nbsp;)</code> on the
    document manager object before calling <code>read()</code>.
    Alternatively, you can set the <code>processImports</code> property
    in the policy file. You can also be more selective, and ignore only
    certain URI's when loading the imported documents.
    To selectively skip certain named imports,
    call the method <code>addIgnoreImport(&nbsp;String&nbsp;uri&nbsp;)</code>
    on the document manager object, or set the <code>ignoreImport</code>
    property in the policy.</p>

    <h3>Managing file references</h3>
        <p>An advantage of working with ontologies is that we can reuse work
    done by other ontologists, by importing their published ontologies into
    our own.
    Sometimes, however, this means that there is an Internet firewall between the ontology-based
    application and the source of an imported ontology. Even if it's possible to
    traverse the firewall through an HTTP proxy, retrieving files from an HTTP
    connection may impose unacceptable delays when starting an application.
    In the worst case, we may find that ontology on which our application depends is
    temporarily or permanently unavailable from the original published URL.
    To alleviate these commonly experienced problems, you can use the
    ontology document manager to set up a
    a local indirection, so that an attempt to import a document from a
    given published URL means that a local copy of the document is retrieved
    instead. This may be a file copy, or simply a pointer to a local
    mirror web site.</p>
    <p>
      To specify this local redirection in the policy file, use the following declarations:
    </p>
<pre class="codesample">&lt;OntologySpec&gt;
  &lt;publicURI rdf:resource="&#133; the public URI to map from&#133;"    /&gt;
  &lt;altURL rdf:resource="&#133; the local URL to map to &#133;" /&gt;
  &lt;!-- optional ontology language term --&gt;
  &lt;language rdf:resource="&#133; encoding used &#133;" /&gt;
  &lt;!-- optional prefix to associate with the public URL --&gt;
  &lt;prefix rdf:datatype="&amp;xsd;string"&gt;a prefix&lt;/prefix&gt;
&lt;/OntologySpec&gt;</pre>
    <p>For example:</p>
<pre class="codesample">&lt;OntologySpec&gt;
  &lt;!-- local version of the RDFS vocabulary --&gt;
  &lt;publicURI rdf:resource="http://www.w3.org/2000/01/rdf-schema"    /&gt;
  &lt;altURL rdf:resource="file:vocabularies/rdf-schema.rdf" /&gt;
&lt;/OntologySpec&gt;</pre>
        <p>This specifies that an attempt to load the RDFS vocabulary from <code>http://www.w3.org/2000/01/rdf-schema</code>
    will transparently cause <code>file:vocabularies/rdf-schema.rdf</code>
    to be fetched instead. You can specify any number of such re-directions
    in the policy file, or you can add them to the document manager object
    directly by calling the various setter methods (see the Javadoc for
    details). As a side-effect, this mechanism also means that ontologies
    may be named with any legal URI (not necessarily resolvable) - so long
    as the <code>altURL</code> is itself resolvable.</p>
    <p>Note that the <code>OntDocumentManager</code> is an application of Jena's
    <a href="../how-to/filemanager.html">File Manager</a>. See the notes on FileManager for details of
    additional options.</p>

  <p> In the following example, I programmatically declare that the ESWC ontology
    is replicated locally on disk, and then I load it using the public URL. Assume that the constant
    <code>JENA</code> has been initialised to the directory in which Jena was installed. </p>
<pre class="codesample">OntModel m = ModelFactory.createOntologyModel();
  OntDocumentManager dm = m.getDocumentManager();
  dm.addAltEntry( "http://www.eswc2006.org/technologies/ontology",
                  "file:" + JENA + "src-examples/data/eswc-2006-09-21.rdf"    );
  m.read( "http://www.eswc2006.org/technologies/ontology" );</pre>

    <h3>Specifying prefixes</h3>

    <p> A model keeps a table of URI prefixes that can be used to render URI's in
      the shortened prefix:name form, which is useful in displaying URI's in a readable
      way in user interfaces, and is essential in producing legal XML names that denote
      arbitrary URI's. The ontology model's table of prefixes can be initialized from
      a table kept by the document manager, which contains the standard prefixes plus
      any that are declared by in the policy file (or added to subsequently by method
      calls). To prevent the model's prefix table from being initialized in this way,
      use the property <code>useDeclaredNsPrefixes</code> in the policy file (with
      value <code>false</code>), or call the method <code>setUseDeclaredPrefixes</code> on the
      ontology object. </p>

    <h3>Caching of imported models</h3>
        <p>You can use the document manager to assist
    with loading ontology documents through its cache. Suppose two
    ontologies, A and B both import ontology C. We would like not to have
    to read C twice when loading A and then B. The document manager supports this
    use case by optionally caching C's model, indexed by URI. When A tries
    to import C, there is no cached copy, so a new model is created for C,
    the contents of C's URL read in to the model, then the C model is used in the
    compound document for A. Subsequently, when ontology B is loading imports,
    the document manager checks in its cache and finds an existing copy
    of C. This will be used in preference to reading a fresh copy of C from
    C's source URL, saving both time and storage space.</p>
        <p>Caching of import models is switched on by default.
    To turn it off, use the policy property <code>cacheModels</code>,
    or call the method <code>setCacheModels(&nbsp;boolean&nbsp;caching&nbsp;)</code>
    with <code>caching = false</code>.
    The document manager's current model cache
    can be cleared at any time by calling <code>clearCache()</code>.</p>

    <h2 id="ontResource">The generic ontology type: OntResource</h2>

<p> All of the classes in the ontology API that represent ontology values have
  <code><a href="../javadoc/com/hp/hpl/jena/ontology/OntResource.html">OntResource</a></code>
  as a common super-class. This makes <code>OntResource</code> a good place to
  put shared functionality for all such classes, and makes a handy common return
  value for general methods. The Java interface <code>OntResource</code> extends
  Jena's RDF <code><a href="../javadoc/com/hp/hpl/jena/rdf/model/Resource.html">Resource</a></code>
  interface, so any general method that accepts a resource or an <code><a href="../javadoc/com/hp/hpl/jena/rdf/model/RDFNode.html">RDFNode</a></code>
  will also accept an <code>OntResource</code>, and consequently, any other ontology
  value. </p>
    <p>
      Some of the common attributes of ontology resources that are expressed through methods on OntResource are shown below:
    </p>
    <table class="definitions" summary="properties of OntResource">
      <tr>
        <th class="def1a">Attribute</th><th class="def1b">Meaning</th>
      </tr>
      <tr>
        <td>versionInfo</td>
        <td>
            A string documenting the version or history of this resource
        </td>
      </tr>
      <tr>
        <td>comment</td>
        <td>
            A general comment associated with this value
        </td>
      </tr>
      <tr>
        <td>label</td>
        <td>
            A human-readable label
        </td>
      </tr>
      <tr>
        <td>seeAlso</td>
        <td>
            Another web location to consult for more information about this resource
        </td>
      </tr>
      <tr>
        <td>isDefinedBy</td>
        <td>
            A specialisation of seeAlso that is intended to supply a definition of this resource
        </td>
      </tr>
      <tr>
        <td>sameAs</td>
        <td>
            Denotes another resource that this resource is equivalent to
        </td>
      </tr>
      <tr>
        <td>differentFrom</td>
        <td>
            Denotes another resource that is distinct from this resource (by definition)
        </td>
      </tr>
    </table>
    <p>
      For each of these properties, there is a standard pattern of available methods:
    </p>
    <table class="definitions" summary="Standard pattern of methods on ontology API Java classes">
      <tr>
        <th class="def1a">
          Method
        </th>
        <th class="def1b">
          Effect
        </th>
      </tr>
      <tr>
        <td>add&lt;property&gt;</td>
        <td>
            Add an additional value for the given property
        </td>
      </tr>
      <tr>
        <td>set&lt;property&gt;</td>
        <td>
            Remove any existing values for the property, then add the given value
        </td>
      </tr>
      <tr>
        <td>list&lt;property&gt;</td>
        <td>
            Return an iterator ranging over the values of the property
        </td>
      </tr>
      <tr>
        <td>get&lt;property&gt;</td>
        <td>
            Return the value for the given property, if the resource has one. If not, return null. If it has more than one value, an arbitrary selection is made.
        </td>
      </tr>
      <tr>
        <td>has&lt;property&gt;</td>
        <td>
            Return true if there is at least one value for the given property. Depending on the name of the property, this is sometimes is&lt;property&gt;
        </td>
      </tr>
      <tr>
        <td>remove&lt;property&gt;</td>
        <td>
            Removes a given value from the values of the property on this resource. Has no effect if the resource does not have that value.
        </td>
      </tr>
    </table>

        <p>For example: <code>addSameAs(&nbsp;Resource&nbsp;r&nbsp;)</code>,
        or <code>isSameAs(&nbsp;Resource&nbsp;r&nbsp;)</code>. For full details
        of the individual methods, please consult the Javadoc.</p>
    <p>
      <code>OntResource</code> defines some other general utility
        methods. For example, to find out how many values a resource has for a
        given property, you can call <code>getCardinality(&nbsp;Property&nbsp;p&nbsp;)</code>.
        To delete the resource from the ontology altogether, you can call <code>remove()</code>.
        The effect of this is to remove every statement that mentions this
        resource as a subject or object of a statement. </p>
      <p>To get or set the value
        of a given property, use <code>getPropertyValue(&nbsp;Property&nbsp;p&nbsp;)</code>
        or <code>setPropertyValue(&nbsp;Property&nbsp;p,&nbsp;RDFNode&nbsp;value&nbsp;)</code>.
        Continuing the naming pattern,
        the values of a named property can be listed (with <code>listPropertyValues</code>),
        removed (with <code>removeProperty</code>) or added (with <code>addProperty</code>). </p>
        <p>Finally, <code>OntResource</code> provides methods for listing,
        getting and setting the <code>rdf:type</code> of a resource, which denotes a
        class to which the resource belongs (remember that in RDF and OWL, a resource can belong
        to many classes at once). The <code>rdf:type</code> property
        is one for which many entailment rules are defined in the semantic
        models of the various ontology languages. Therefore, the values that <code>listRDFTypes()</code>
        returns is more than usually dependent on the actual reasoner bound to
        the ontology model. For example, suppose I have class A, class B which
        is a subclass of A, and resource x whose asserted <code>rdf:type</code>
        is B. With no reasoner, listing x's RDF types will return only B. If the
        reasoner is able to calculate the closure of the subclass hierarchy (and
        most can), X's RDF types would also include A. A complete OWL
        reasoner would also infer that x has <code>rdf:type</code> <code>owl:Thing</code>
        and <code>rdf:Resource</code>.
        </p>
        <p>For some tasks, getting a complete list of the RDF types of a
      resource is exactly what is needed. For other tasks, this is not the
      case. If you are developing an ontology editor, for example,
      you may want to distinguish in its
      display between inferred and asserted types. In the above example, only
      <code>x&nbsp;rdf:type&nbsp;B</code> is asserted, everything else is
      inferred. One way to make this distinction is to make use of the base
      model (see Figure 4). Getting the resource from the base model and
      listing the type properties there would return only the asserted values.
      For example:     </p>
<pre class="codesample">// create the base model
String SOURCE = &quot;http://www.eswc2006.org/technologies/ontology&quot;;
String NS = SOURCE + &quot;#&quot;;
OntModel base = ModelFactory.createOntologyModel( OWL_MEM );
base.read( SOURCE, &quot;RDF/XML&quot; );

// create the reasoning model using the base
OntModel inf = ModelFactory.createOntologyModel( OWL_MEM_MICRO_RULE_INF, base );

// create a dummy paper for this example
OntClass paper = base.getOntClass( NS + &quot;Paper&quot; );
Individual p1 = base.createIndividual( NS + &quot;paper1&quot;, paper );

// list the asserted types
for (Iterator i = p1.listRDFTypes(); i.hasNext(); ) {
    System.out.println( p1.getURI() + &quot; is asserted in class &quot; + i.next() );
}

// list the inferred types
p1 = inf.getIndividual( NS + &quot;paper1&quot; );
for (Iterator i = p1.listRDFTypes(); i.hasNext(); ) {
    System.out.println( p1.getURI() + &quot; is inferred to be in class &quot; + i.next() );
}</pre>
    <p id="direct_relationships">For other user interface or
    presentation tasks, we may want something between the complete list of
    types and the base list of only the asserted values. Consider the
    class hierarchy in figure 5 (i):</p>
    <p class="centered">
      <img src="../images/Direct-hierarchy.png" width="595" height="315" alt="Diagram showing direct relationships" />
    </p>
    <p class="caption">
      Figure 5: asserted and inferred relationships
    </p>
    <p>Figure 5 (i) shows a base model, containing a class hierarchy and
    an instance x. Figure 5 (ii) shows the full set of relationships that might
    be inferred from this base model. In Figure 5 (iii), we see only the <em>direct</em>
    or maximally specific relationships. For example, in 5 (iii) x does not
    have <code>rdf:type A</code>, since this is an relationship that is
    covered by the facts that x has <code>rdf:type D</code>, and D is a
    subclass of A. Notice also that the <code>rdf:type B</code> link is also
    removed from the direct graph, for a similar reason. Thus the direct
    graph hides relationships from both the inferred and asserted graphs.
    When displaying instance x in a GUI, particularly in a tree view of some
    kind, the direct graph is often the most useful as it contains the
    useful information in the most compact form.</p>
    <p>
      To list the RDF types of a resource, use:
    </p>
<pre class="codesample">listRDFTypes()                 // assumes not-direct
listRDFTypes( boolean direct ) // if direct=true, show only direct relationships</pre>
    <p>
      Related methods allow the <code>rdf:type</code> to be tested, set and returned.
    </p>

    <h2 id="classesBasic">Ontology classes and basic class expressions</h2>

    <p> Classes are the basic building blocks of an ontology. A simple class is represented
      in Jena by an <a href="../javadoc/com/hp/hpl/jena/ontology/OntClass.html">OntClass</a>
      object. As I <a href="#rdfPolymorphism">mentioned above</a>, an ontology class
      is a facet of an RDF resource. One way, therefore, to get an ontology class
      is to convert an RDF resource. Assume that <code>m</code> is a suitable defined
      <code>OntModel</code>, into which the ESWC ontology has already been read, and that
      <code>NS</code> is a variable denoting the ontology namespace:
    </p>
<pre class="codesample">Resource r = m.getResource( NS + "Paper" );
OntClass paper = (OntClass) r.as( OntClass.class );</pre>

    <p> This can be shortened by calling <code>getOntClass()</code> on the ontology
      model: </p>
<pre class="codesample">OntClass paper = m.getOntClass( NS + "Paper" );</pre>
    <p>The <code>getOntClass</code> method will retrieve the resource with
    the given URI, and attempt to obtain the <code>OntClass</code> facet. If either of
    these operations fail, <code>getOntClass()</code>
    will return null. Compare this with the <code>createClass</code>
    method, which will reuse an existing resource if possible,
    or create a new class resource if not:</p>
<pre class="codesample">OntClass paper     = m.createClass( NS + "Paper" );
OntClass bestPaper = m.createClass( NS + "BestPaper" );</pre>
    <p>You can use the create class method to create an anonymous
    class &#150; a class description with no associated URI. Anonymous classes
    are often used when building more complex ontologies in OWL or DAML. They are
    less useful in RDFS.</p>
<pre class="codesample">OntClass anonClass = m.createClass();</pre>
    <p>Once you have the ontology class object, you can begin processing
    it through the methods defined on <code>OntClass</code>. The attributes
    of a class are handled in a similar way to the attributes of
    OntResource, above, with a collection of methods to set, add, get, test,
    list and remove values. Properties of classes that are handled in this way
    are:</p>
    <table class="definitions" summary="Characteristics of ontology classes handled through the OntClass API">
      <tr>
        <th class="def1a">
          Attribute
        </th>
        <th class="def1b">
          Meaning
        </th>
      </tr>
      <tr>
        <td>subClass</td>
        <td>
            A subclass of this class, i.e. those classes that are declared <code>subClassOf</code> this class.
        </td>
      </tr>
      <tr>
        <td>superClass</td>
        <td>
            A super-class of this class, i.e. a class that this class is a <code>subClassOf</code>.
        </td>
      </tr>
      <tr>
        <td>equivalentClass</td>
        <td>
            A class that represents the same concept as this class. This is not just having the same class extension: the class 'British Prime Minister in 2003' contains the same individual as the class 'the husband of Cherie Blair', but they represent different concepts.
        </td>
      </tr>
      <tr>
        <td>disjointWith</td>
        <td>
            Denotes a class with which this class has no instances in common.
        </td>
      </tr>
    </table>

    <p>
      Thus, in our example ontology, we can print a list the subclasses of an Artefact as follows:
    </p>
<pre class="codesample">OntClass artefact = m.getOntClass( NS + &quot;Artefact&quot; );
for (Iterator i = artefact.listSubClasses(); i.hasNext(); ) {
  OntClass c = (OntClass) i.next();
  System.out.println( c.getURI() );
}</pre>
    <p>Note that, under RDFS and OWL semantics, each class is a sub-class of itself
    (in other words, <code>rdfs:subClassOf</code> is reflexive). While this is true,
    under the semantics, Jena users have reported finding it unhelpful. Therefore,
    the <code>listSubClasses</code> and <code>listSuperClasses</code> methods remove
    the reflexive from the list of results returned by the iterator. However, if you
    use the plain <code>Model</code> API to query for <code>rdfs:subClassOf</code>
    triples, assuming that a reasoner is in use, the reflexive triple will appear
    in the deductions model.</p>

    <p>Given an <code>OntClass</code> object, you can create or remove members of
    the class extension &#150; individuals that are instances of the class &#150;
    using the following methods:
    </p>

    <table class="definitions" summary="OntClass instance-related methods">
      <tr>
        <th class="def1a">
          Method
        </th>
        <th class="def1b">
          Meaning
        </th>
      </tr>
      <tr>
        <td>listInstances()<br />listInstances( boolean direct )</td>
        <td>
            Returns an iterator over those instances that include this class among
            their <code>rdf:type</code> values. The <code>direct</code> flag can be
            used to select individuals that are direct members of the class, rather
            than indirectly through the class hierarchy. Thus if <code>p1</code> has
            <code>rdf:type :Paper</code>, it will appear in the iterator returned by
            <code>listInstances</code> on <code>:Artefact</code>, but not in the
            iterator returned by <code>listInstances(false)</code> on <code>:Artefact</code>.
        </td>
      </tr>
      <tr>
        <td>createIndividual()<br />createIndividual( String uri )</td>
        <td>
            Adds a resource to the model, whose asserted <code>rdf:type</code> is
            this ontology class. If no URI is given, the individual is an anonymous
            resource.
        </td>
      </tr>
      <tr>
        <td>dropIndividual( Resource individual )</td>
        <td>
          Removes the association between the given individual and this ontology class.
          Effectively, this removes the <code>rdf:type</code> link between this class
          and the resource. Note that this is not the same as removing the individual
          altogether, unless the only thing that is known about the resource is that
          it is a member of the class. To delete an <code>OntResource</code>, including
          classes and individuals, use the <code>remove()</code> method.
        </td>
      </tr>
    </table>


        <p>To test whether a class is a root of the class hierarchy in this
        model (i.e. it has no known super-classes), call <code>isHierarchyRoot()</code>.</p>
    <p>The domain of a property
    is intended to allow entailments about the class of an individual, given
    that it appears as a statement subject. It is not a constraint that can
    be used to validate a document, in the way that XML schema can do.
    Nevertheless, many developers find it convenient to use the domain of a
    property to document the design intent that the property only applies to
    known instances of the domain class. Given this observation, it can be a
    useful debugging or display aide to show the properties that have this
    class among their domain classes. The method <code>listDeclaredProperties()</code>
    attempts to identify the properties that are intended to apply to
    instances of this class. Using <code>listDeclaredProperties</code> is
    explained in detail in the <a href="../how-to/rdf-frames.html">RDF frames how-to</a>.</p>

    <h2 id="properties">Ontology properties</h2>

    <p>In an ontology, a <em>property</em> denotes the name of a relationship between resources, or between a resource
    and a data value. It corresponds to a predicate in logic representations. One interesting aspect of
    languages like RDFS and OWL is that properties are not defined as aspects of some enclosing
    class, but are first-class objects in their own right. This means that ontologies and ontology-applications
    can store, retrieve and make assertions about properties directly. Consequently, Jena has a set of Java classes
    that allow you to conveniently manipulate the properties represented in an ontology model.</p>
    <p>A property in an ontology model is an extension of the core Jena API class
    <code><a href="../javadoc/com/hp/hpl/jena/rdf/model/Property.html">Property</a></code>,
  and allows access to the additional information that can be asserted about properties
  in an ontology language. The common API super-class for representing ontology properties
  in Java is <code><a href="../javadoc/com/hp/hpl/jena/ontology/OntProperty.html">OntProperty</a></code>.
  Again, using the pattern of add, set, get, list, has, and remove methods, we
  can access the following attributes of an <code>OntProperty</code>: </p>
    <table class="definitions" summary="Characteristics of properties handled by the OntProperty API">
      <tr>
        <th class="def1a">Attribute</th>
        <th class="def1b">Meaning</th>
      </tr>
      <tr>
        <td>subProperty</td>
        <td>
            A sub property of this property; i.e. a property which is declared to be a <code>subPropertyOf</code> this property. If p is a sub property of q, and we know that <code>A&nbsp;p&nbsp;B</code> is true, we can infer that <code>A&nbsp;q&nbsp;B</code> is also true.
        </td>
      </tr>
      <tr>
        <td>superProperty</td>
        <td>
            A super property of this property, i.e. a property that this property is a <code>subPropertyOf</code>
        </td>
      </tr>
      <tr>
        <td>domain</td>
        <td>
            Denotes the class or classes that form the domain of this property. Multiple domain values are interpreted as a conjunction. The domain denotes the class of value the property maps from.
        </td>
      </tr>
      <tr>
        <td>range</td>
        <td>
            Denotes the class or classes that form the range of this property. Multiple range values are interpreted as a conjunction. The range denotes the class of values the property maps to.
        </td>
      </tr>
      <tr>
        <td>equivalentProperty</td>
        <td>
            Denotes a property that is the same as this property.
        </td>
      </tr>
      <tr>
        <td>inverse</td>
        <td>
            Denotes a property that is the inverse of this property. Thus if q is the inverse of p, and we know that <code>A q B</code>, then we can infer that <code>B p A</code>.
        </td>
      </tr>
    </table>

        <p>In the example ontology, the property <code>hasProgramme</code> has a domain of
        <code>OrganizedEvent</code>, a range of <code>Programme</code> and the human-readable
        label &quot;has programme&quot;.
        I can reconstruct this definition in an empty ontology model as follows:</p>
<pre class="codesample">OntModel m = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM );
OntClass programme = m.createClass( NS + "Programme" );
OntClass orgEvent = m.createClass( NS + "OrganizedEvent" );

ObjectProperty hasProgramme = m.createObjectProperty( NS + "hasProgramme" );

hasProgramme.addDomain( orgEvent );
body.addRange( programme );
body.addLabel( "has programme", "en" );</pre>

    <p>As a further example, I can alternatively add information to an existing ontology. Let's
    add a super-property <code>hasDeadline</code> to generalise the separate properties denoting
    the submission deadline, notification deadline and camera-ready deadline:</p>
<pre class="codesample">OntModel m = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM );
m.read( &quot;http://www.eswc2006.org/technologies/ontology&quot; );

DatatypeProperty subDeadline = m.getDatatypeProperty( NS + &quot;hasSubmissionDeadline&quot; );
DatatypeProperty notifyDeadline = m.getDatatypeProperty( NS + &quot;hasNotificationDeadline&quot; );
DatatypeProperty cameraDeadline = m.getDatatypeProperty( NS + &quot;hasCameraReadyDeadline&quot; );

DatatypeProperty deadline = m.createDatatypeProperty( NS + &quot;deadline&quot; );
deadline.addDomain( m.getOntClass( NS + &quot;Call&quot; ) );
deadline.addRange( XSD.dateTime );

deadline.addSubProperty( subDeadline );
deadline.addSubProperty( notifyDeadline );
deadline.addSubProperty( cameraDeadline );
</pre>
    <p>Note that, although I called the <code>addSubProperty</code> method on the object representing
    the new super-property, the serialized form of the
    ontology will contain <code>rdfs:subPropertyOf</code> axioms on each of the sub-property resources,
    since this is what the language defines. Jena will, in general, try to allow symmetric access to
    sub-properties and sub-classes from either direction.</p>

    <h3 id="propertyTypes">Object and Datatype properties</h3>
    <p>
      OWL and DAML+OIL refine the basic property type from RDF into two sub-types:
      <em>object properties</em> and <em>datatype properties</em>
      (for more details see [<a href="http://www.w3.org/TR/owl-ref/#Property">OWL Reference</a>]).
      The difference between
      them is that an object property can have only individuals in its range, while a datatype
      property has concrete data literals (only) in its range. Some OWL reasoners are able to
      exploit the differences between object and datatype properties to perform more efficient
      reasoning over ontologies. OWL also adds an <em>annotation property</em>, which is defined
      to have no semantic entailments, and so is useful when annotating ontology documents, for example.
    </p>

    <p> In Jena, the Java interfaces
      <code><a href="../javadoc/com/hp/hpl/jena/ontology/ObjectProperty.html">ObjectProperty</a></code>,
      <code><a href="../javadoc/com/hp/hpl/jena/ontology/DatatypeProperty.html">DatatypeProperty</a></code> and
      <code><a href="../javadoc/com/hp/hpl/jena/ontology/AnnotationProperty.html">AnnotationProperty</a></code>
      are sub-types of <code>OntProperty</code>. However, they do not have any behaviours
      (methods) particular to themselves. Their existence allows the more complex
      sub-types of ObjectProperty &#150; transitive properties and so forth &#150; to be kept
      separate in the class hierarchy. However, when you create an object property or datatype property
      in a model, it
      will have the effect of asserting different <code>rdf:type</code> statements
      into the underlying triple store. </p>

    <h3 id="functionalProperties">Functional properties</h3>
    <p>OWL permits object and datatype properties to be <em>functional</em>
      &#150; that is, for a given individual in the domain, the range value will always
      be the same. In particular, if <code>father</code> is a functional property,
      and individual <code>:bryn</code> has <code>father&nbsp;:ijd</code> and <code>father&nbsp;:ian</code>,
      a reasoner is entitled to conclude that <code>:ijd</code> and <code>:ian</code>
      denote the same individual.
      A functional property is equivalent to stating that the property has a maximum
      cardinality of one.</p>
      <p>Being a functional property is represented through the
      <code><a href="../javadoc/com/hp/hpl/jena/ontology/FunctionalProperty.html">FunctionalProperty</a></code>
      facet of an ontology property object. If a property is declared functional
      (test using the <code>isFunctional()</code> method), then the method
      <code>asFunctionalProperty()</code> conveniently returns the functional facet.
      A non-functional property can be made functional through the
      <code>convertToFunctionalProperty()</code> method. When you are creating
      a property object, you also have the option of passing a Boolean parameter
      to the <code>createObjectProperty()</code> method on <code>OntModel</code>.
    </p>

    <h3 id="otherPropertyTypes">Other property types</h3>

    <p> There are several additional sub-types of ObjectProperty that represent additional
      capabilities of ontology properties. A
      <code><a href="../javadoc/com/hp/hpl/jena/ontology/TransitiveProperty.html">TransitiveProperty</a></code>
      means that if p is transitive, and we know <code>:a&nbsp;p&nbsp;:b</code> and also
      <code>b&nbsp;p&nbsp;:c</code>, we can infer that <code>:a&nbsp;p&nbsp;:c</code>. A
      <code><a href="../javadoc/com/hp/hpl/jena/ontology/SymmetricProperty.html">SymmetricProperty</a></code>
      means that if p is symmetric, and we know <code>:a&nbsp;p&nbsp;:b</code>, we can infer
      <code>:b&nbsp;p&nbsp;:a</code>. An
      <code><a href="../javadoc/com/hp/hpl/jena/ontology/InverseFunctionalProperty.html">InverseFunctionalProperty</a></code>
      means that for any given range element, the domain value is unique. (Note that
      in DAML+OIL, the terminology for inverse functional property is <em>unambiguous
      property</em>). </p>

    <p> Given that all properties are <code>RDFNode</code> objects, and therefore
      support the <code>as()</code> method, you can use <code>as()</code> to change
      from an object property facet to a transitive property facet. To make this more
      straightforward, the <code>OntProperty</code> Java class has a number of methods
      that support directly switching to the corresponding facet view: </p>
<pre class="codesample">public TransitiveProperty asTransitiveProperty();
public FunctionalProperty asFunctionalProperty();
public SymmetricProperty asSymmetricPropery();
public InverseFunctionalProperty asInverseFunctionalProperty();</pre>

    <p> These methods all assume that the underlying model will support this change
      in perspective. If not, the operation will fail with a <code>ConversionException</code>.
      For example, if
      a given property <code>p</code> is not already a transitive property, then invoking
      <code>p.asTransitiveProperty()</code> will throw a conversion exception.
      The following methods will, if necessary, add additional information
      (i.e. the additional <code>rdf:type</code> statement) to allow the conversion
      to an alternative facet to succeed. </p>
<pre class="codesample">public TransitiveProperty convertToTransitiveProperty();
public FunctionalProperty convertToFunctionalProperty();
public SymmetricProperty convertToSymmetricPropery();
public InverseFunctionalProperty convertToInverseFunctionalProperty();</pre>

    <p>Finally, methods beginning <code>is&#133;</code> (e.g. <code>isTransitiveProperty</code>)
    allow you to test whether a given property would support a given sub-type facet.</p>

    <h2 id="classesComplex">More complex class expressions</h2>

    <p>I introduced the handling of basic, named classes above.
    These are the only kind of class descriptions
    available in RDFS. In OWL, however, there are a number of
    additional types of class expression, which allow richer and more
    expressive descriptions of concepts. There are two main categories of
    additional class expression: <em>restrictions</em> and <em>Boolean
    expressions</em>. Let's examine each in turn.</p>

    <h3 id="restrictions">Restriction class expressions</h3>

    <p> A <a href="../javadoc/com/hp/hpl/jena/ontology/Restriction.html">restriction</a>
      defines a class by reference to one of the properties of the individuals that
      comprise the members of the class, and then placing some constraint on that property.
      For example, in a simple view of animal taxonomy, we might say that mammals
      are covered in fur, and birds in feathers. Thus the property <code>hasCovering</code>
      is in one case restricted to have the value <code>fur</code>, in the other to
      have the value <code>feathers</code>. This is a <em>has value restriction</em>.
      Six restriction types are currently defined by OWL: </p>

    <table class="definitions" summary="Different types of restrictions in OWL">
      <tr>
        <th class="def2a">Restriction type</th><th class="def2b">Meaning</th>
      </tr>
      <tr>
        <td>has value</td>
        <td>
            The restricted property has exactly the given value.
        </td>
      </tr>
      <tr>
        <td>all values from</td>
        <td>
            All values of the restricted property, if it has any, are members of the given class.
        </td>
      </tr>
      <tr>
        <td>some values from</td>
        <td>
            The property has at least one value which is a member of the given class.
        </td>
      </tr>
      <tr>
        <td>cardinality</td>
        <td>
            The property has exactly <em>n</em> values, for some positive integer n.
        </td>
      </tr>
      <tr>
        <td>min cardinality</td>
        <td>
            The property has at least <em>n</em> values, for some positive integer n.
        </td>
      </tr>
      <tr>
        <td>max cardinality</td>
        <td>
            The property has at most <em>n</em> values, for some positive integer n.
        </td>
      </tr>
    </table>

    <p>Note that in DAML+OIL terminology, an all-values-from restriction
    is a <em>toClass</em> restriction, while a some-values-from restriction
    is a <em>hasClass</em> restriction. Note also that, at present, the Jena
    ontology API has only limited support for DAML's qualified cardinality
    restrictions (i.e. <code>cardinalityQ</code>, <code>minCardinalityQ</code>
    and <code>maxCardinalityQ</code>). Qualified cardinality restrictions
    are encapsulated in the interfaces <code>CardinalityQRestriction</code>,
    <code>MinCardinalityQRestriction</code> and <code>CardinalityQRestriction</code>.
    <code>OntModel</code> also provides methods for creating and accessing
    qualified cardinality restrictions. Since they are not part of the
    OWL 1.0 language definition, qualified cardinality restrictions are not
    supported in OWL ontologies. Qualified cardinality restrictions may be added
    to the forthcoming OWL 1.1 update, at which point it is likely
    that the Jena ontology API will be updated. Note however, that we are not currently
    making any commitment on the timescale for such an update.</p>

    <p>Jena provides a number of ways of creating restrictions, or
    retrieving them from a model. Firstly, you can retrieve a general restriction
    from the model by its URI, if known.</p>

<pre class="codesample">// get restriction with a given URI
Restriction r = m.getRestriction( NS + &quot;theName&quot; );
</pre>

    <p>You can create a new restriction created by
    nominating the property that the restriction applies to:</p>
<pre class="codesample">// anonymous restriction on property p
OntProperty p = m.createOntProperty( NS + &quot;p&quot; );
Restriction anonR = m.createRestriction( p );</pre>

    <p>Since a restriction is typically not assigned a URI in an ontology,
    retrieving an existing restriction by name may not be possible. However,
    you can list all of the restrictions in a model and search for the
    one you want:</p>

<pre class="codesample">Iterator i = m.listRestrictions();
while (i.hasNext()) {
    Restriction r = (Restriction) i.next();
    if (isTheOne( r )) {
        // handle the restriction
    }
}</pre>
    <p>A common case is that you want the restrictions on some property <code>p</code>.
    In this case, from an object denoting <code>p</code> you can list the restrictions
    that mention that property:</p>
<pre class="codesample">OntProperty p = m.getProperty( NS + &quot;p&quot; );
Iterator i = p.listReferringRestrictions();
while (i.hasNext()) {
    Restriction r = (Restriction) i.next();
    // now handle the restriction &#133;
}</pre>

    <p>
      A general restriction can be converted to a specific type of restriction via
      <code>as&#133;</code> methods (if the information is already in the model), or, if
      the information is not in the model, via <code>convertTo&#133;</code> methods.
      For example, to convert the example restriction <code>r</code>
      from the example above to an all values from restriction, you can do the following:
    </p>

<pre class="codesample">OntClass c = m.createClass( NS + &quot;SomeClass&quot; );
AllValuesFromRestriction avf = r.convertToAllValuesFromRestriction( c );</pre>

    <p>To create a particular restriction <em>ab initio</em>, you can use the creation
      methods defined on <code>OntModel</code>. For example: </p>
<pre class="codesample">OntClass c = m.createClass( NS + "SomeClass" );
ObjectProperty p = m.createObjectProperty( NS + "p" );

// null denotes the URI in an anonymous restriction
AllValuesFromRestriction avf = m.createAllValuesFromRestriction( null, p, c );</pre>

    <p>
      Assuming that the above code fragment was using a model <code>m</code> that was created
      with the OWL language profile, it creates a instance of an OWL restriction that would have
      the following definition in RDF/XML:
    </p>
<pre class="codesample">&lt;owl:Restriction&gt;
  &lt;owl:onProperty rdf:resource="#p"/&gt;
  &lt;owl:allValuesFrom rdf:resource="#SomeClass"/&gt;
&lt;/owl:Restriction&gt;</pre>

    <p>
      Once you have a particular restriction object, there are methods following the
      standard add, get, set and test naming pattern to access the aspects of the restriction.
      For example, in a camera ontology, we might find this definition of a class
      describing Large-Format cameras:
    </p>
<pre class="codesample">&lt;owl:Class rdf:ID="Large-Format"&gt;
  &lt;rdfs:subClassOf rdf:resource="#Camera"/&gt;
  &lt;rdfs:subClassOf&gt;
    &lt;owl:Restriction&gt;
      &lt;owl:onProperty rdf:resource="#body"/&gt;
      &lt;owl:allValuesFrom rdf:resource="#BodyWithNonAdjustableShutterSpeed"/&gt;
   &lt;/owl:Restriction&gt;
  &lt;/rdfs:subClassOf&gt;
&lt;/owl:Class&gt;</pre>

    <p>Here's one way to access the components of the all values from restriction.
    Assume m contains a suitable camera ontology:</p>
<pre class="codesample">OntClass largeFormat = m.getOntClass( camNS + "Large-Format" );
for (Iterator i = LargeFormat.listSuperClasses( true ); i.hasNext(); ) {
  OntClass c = (OntClass) i.next();

  if (c.isRestriction()) {
    Restriction r = c.asRestriction();

    if (r.isAllValuesFromRestriction()) {
      AllValuesFromRestriction av = r.asAllValuesFromRestriction();
      System.out.println( "AllValuesFrom class " +
                          av.getAllValuesFrom().getURI() +
                          " on property " + av.getOnProperty().getURI() );
    }
  }
}</pre>

    <h3 id="booleanClassExprs">Boolean class expressions</h3>
    <p>Most programmers are familiar with the use of Boolean operators
    to construct propositional expressions: conjunction (and), disjunction
    (or) and negation (not). OWL provides a means for
    construction expressions describing classes with analogous operators, by
    considering class descriptions in terms of the set of individuals that
    comprise the members of the class.</p>
    <p>Suppose we wish to say that an
    instance x has <code>rdf:type</code> A <strong>and</strong> <code>rdf:type</code>
    B. This means that x is both a member of the set of individuals in A,
    and in the set of individuals in B. Thus, x lies in the <em>intersection</em>
    of classes A and B. If, on the other hand, A is either has <code>rdf:type</code>
    A <strong>or</strong> B, then x must lie in the <em>union</em> of A and
    B. Finally, to say that x does <strong>not</strong> have <code>rdf:type</code>
    A, it must lie in the <em>complement</em> of A. These operations, union,
    intersection and complement are the Boolean operators for constructing
    class expressions. While complement takes only a single argument, union
    and intersection must necessarily take more than one argument. Before
    continuing with constructing and using Boolean class expressions, I
    digress briefly to discuss lists.</p>

    <h3 id="listExpressions">List expressions</h3>
    <p>
      RDF originally had three container types: <code>Seq</code>,
      <code>Alt</code> and <code>Bag</code>. While useful, these are
      all open forms: it is not possible to say that a given container has a fixed number
      of values. The DAML+OIL standard introduced a fourth container type - lists - in
      order to have a closed collection. Lists have subsequently been added to the core RDF
      specification, and are used extensively in OWL.
      A list follows the well-known <em>cons cell</em> pattern from Lisp, Prolog and other
      list-handling languages. Each cell of a list is either the end-of-list terminator
      (<code>nil</code> in Lisp), or is a pair consisting of a value and a pointer to the
      cell that is the first cell on the tail of the list. In RDF lists, the end-of-list is
      marked by a resource with name <code>rdf:nil</code>, while each list cell is an anonymous
      resource with two properties, one denoting the tail and the other the value.
      Fortunately, this complexity is hidden by some simple syntax:
    </p>
<pre class="codesample">&lt;p rdf:parseType="collection"&gt;
  &lt;A /&gt;
  &lt;B /&gt;
&lt;/p&gt;</pre>
    <p>
      According to the RDF specification, this list of two elements has the
      following expansion as RDF triples:
    </p>
<pre class="codesample">&lt;p&gt;
  &lt;rdf:first&gt;&lt;A /&gt;&lt;/rdf:first&gt;
  &lt;rdf:rest&gt;
    &lt;rdf:first&gt;&lt;B /&gt;&lt;/rdf:first&gt;
    &lt;rdf:rest rdf:resource="http://www.w3.org/1999/02/22-rdf-syntax-ns#nil"/&gt;
  &lt;/rdf:rest&gt;
&lt;/p&gt;</pre>
<p>Given this construction, a well formed list (one with
exactly one <code>rdf:first</code> and <code>rdf:rest</code> per cons
cell) has a precisely determined set of members. Incidentally, the
same list in N3/Turtle is even more compact:</p>
<pre class="codesample">:example
    :p ( :A :B ).</pre>

<p> Although lists
  are defined in the generic RDF model in Jena, they are extensively used by the
  ontology API so I mention them here. Full details of the methods defined on
  the <a href="../javadoc/com/hp/hpl/jena/rdf/model/RDFList.html"><code>RDFList</code></a>
  class are available in the Jena Javadoc. </p>

<p> A number of means of constructing lists is defined in
<a href="../javadoc/com/hp/hpl/jena/rdf/model/Model.html"><code>Model</code></a>,
  as variants on <code>createList</code>. For example, you can construct
  a list of three classes as follows: </p>
    <pre class="codesample">OntModel m = ModelFactory.createOntModel();
OntClass c0 = m.createClass( NS + "c0" );
OntClass c1 = m.createClass( NS + "c1" );
OntClass c2 = m.createClass( NS + "c2" );

RDFList cs = m.createList( new RDFNode[] {c0, c1, c2} );</pre>
    <p>
      Alternatively, you can build a list one element at at time:
    </p>
    <pre class="codesample">OntModel m = ModelFactory.createOntModel();
RDFList cs = m.createList(); // Cs is empty
cs = cs.cons( m.createClass( NS + "c0" ) );
cs = cs.cons( m.createClass( NS + "c1" ) );
cs = cs.cons( m.createClass( NS + "c2" ) );</pre>

    <p>Note that these two approaches end with the classes in the lists
    in opposite orders, since the <code>cons</code> operation adds a new
    list cell to the front of the list. Thus the second list will run c2 to
    c0. In the ontology operations we are discussing here, the order of
    values in the list is not considered significant.</p>

    <p>Once the list has been constructed or obtained from the model (a
    resource which is a cell in a list sequence will accept <code>.as(&nbsp;RDFList.class&nbsp;)</code>),
    <a href="../javadoc/com/hp/hpl/jena/rdf/model/RDFList.html"><code>RDFList</code></a>
    methods may be used to access members of the list, iterate over
    the list, and so forth. For example:</p>

<pre class="codesample">System.out.println( "List has " + myRDFList.size() + " members:" );
for (Iterator i = myRDFList.iterator(); i.hasNext(); ) {
  System.out.println( i.next() );
}</pre>

    <h3 class="booleanExprs">Intersection, union and complement class expressions</h3>

    <p>Given Jena's ability to construct lists, building intersection and union
    class expressions is straightforward. The <code>create</code> methods on OntModel
    allow you to construct an intersection or union directly.
    Alternatively, given an existing OntClass, you can use the <code>convertTo&#133;</code> methods
    to construct facet representing the more specialised expressions.
    For example, we can define the class of UK industry-related conferences as the
    intersection of conferences with a UK location and conferences with an
    industrial track. Here's the XML declaration:</p>
<pre class="codesample">&lt;owl:Class rdf:ID="UKIndustrialConference"&gt;
  &lt;owl:intersectionOf rdf:parseType="Collection"&gt;
    &lt;owl:Restriction&gt;
      &lt;owl:onProperty rdf:resource="#hasLocation"/&gt;
      &lt;owl:hasValue rdf:resource="#united_kingdom"/&gt;
    &lt;/owl:Restriction&gt;
  &lt;/owl:intersectionOf&gt;
    &lt;owl:Restriction&gt;
      &lt;owl:onProperty rdf:resource="#hasPart"/&gt;
      &lt;owl:someValuesFrom rdf:resource="#IndustryTrack"/&gt;
    &lt;/owl:Restriction&gt;
  &lt;/owl:intersectionOf&gt;
&lt;/owl:Class&gt;</pre>
    <p>Or, more compactly in N3/Turtle:</p>
<pre class="codesample">:UKIndustrialConference a owl:Class
    ; owl:intersectionOf (
       [a owl:Restriction
        ; owl:onProperty :hasLocation
        ; owl:hasValue :united_kingdom]
       [a owl:Restriction
        ; owl:onProperty :hasPart
        ; owl:someValuesFrom :IndustryTrack]
      )</pre>
    <p>
      Here is code to create this class declaration using Jena, assuming that <code>m</code>
      is a model into which the ESWC ontology has been read:
    </p>
<pre class="codesample">// get the class references
OntClass place = m.getOntClass( NS + "Place" );
OntClass indTrack = m.getOntClass( NS + "IndustryTrack" );

// get the property references
ObjectProperty hasPart = m.getObjectProperty( NS + "hasPart" );
ObjectProperty hasLoc = m.getObjectProperty( NS + "hasLocation" );

// create the UK instance
Individual uk = place.createIndividual( NS + "united_kingdom" );

// now the anonymous restrictions
HasValueRestriction ukLocation =
    m.createHasValueRestriction( null, hasLoc, uk );
SomeValuesFromRestriction hasIndTrack =
    m.createHasValueRestriction( null, hasPart, indTrack );

// finally create the intersection class
IntersectionClass ukIndustrialConf =
    m.createIntersectionClass( NS + "UKIndustrialConference",
                               m.createList( new RDFNode[] {ukLocation, hasIndTrack} ) );</pre>

    <p> Given the similarity between union and intersection class expressions, rather
    than separate methods to set the components of the expression, Jena defines
    a common super-class
    <code><a href="../javadoc/com/hp/hpl/jena/ontology/BooleanClassDescription.html">BooleanClassDescription</a></code>.
    This class provides access to the <em>operands</em> to the expression. In the above
    example, the operands are the two restrictions. The
    <code>BooleanClassDescription</code> class allows you to set the operands <em>en
    masse</em> by supplying a list, or to be added or deleted one at a time.</p>

    <p>Complement class expressions are very similar. The
    principal difference is that they take only a single class as operand,
    and therefore do not accept a list of operands.</p>

    <h3 id="enumeratedClasses">Enumerated classes</h3>

    <p> The final type class expression allows by OWL is the enumerated
      class. Recall that a class is a set of individuals. Often, we want to define
      the members of the <em>implicitly</em>: for example, &quot;the class of UK conferences&quot;.
      Sometimes
      it is convenient to define a class <em>explicitly</em>, by stating the individuals
      the class contains. An <em><a href="../javadoc/com/hp/hpl/jena/ontology/EnumeratedClass.html">enumerated
      class</a></em> is exactly the class whose members are the given individuals.
      For example, we know that the class of PrimaryColours contains exactly red,
      green and blue, and no others. </p>

    <p>In Jena, an enumerated class is created in a similar way to other
    classes. The set of values that comprise the enumeration is described by
    an RDFList. For example, here's a class defining the countries that comprise
    the United Kingdom:</p>
<pre class="codesample">&lt;owl:Class rdf:ID="UKCountries"&gt;
  &lt;owl:oneOf rdf:parseType="Collection"&gt;
    &lt;eswc:Place rdf:about="#england"/&gt;
    &lt;eswc:Place rdf:about="#scotland"/&gt;
    &lt;eswc:Place rdf:about="#wales"/&gt;
    &lt;eswc:Place rdf:about="#northern_ireland"/&gt;
  &lt;/owl:oneOf&gt;
&lt;/owl:Class&gt;</pre>
    <p>
      To list the contents of this enumeration, we could do the following:
    </p>
<pre class="codesample">OntClass place = m.getOntClass( NS + "Place" );

EnumeratedClass ukCountries =
    m.createEnumeratedClass( NS + "UKCountries", null );
ukCountries.addOneOf( place.createIndividual( NS + "england" ) );
ukCountries.addOneOf( place.createIndividual( NS + "scotland" ) );
ukCountries.addOneOf( place.createIndividual( NS + "wales" ) );
ukCountries.addOneOf( place.createIndividual( NS + "northern_ireland" ) );

for (Iterator i = UKCountries.listOneOf(); i.hasNext(); ) {
  Resource r = (Resource) i.next();
  System.out.println( r.getURI() );
}</pre>

    <h3 id="listingClasses">Listing classes</h3>

    <p> In many applications, you will need to inspect the set of classes in an
      ontology. The <code>list&#133;</code> methods on <code>OntModel</code> provide a variety of
      means of listing types of class. The methods available include: </p>
<pre class="codesample">public ExtendedIterator listClasses();
public ExtendedIterator listEnumeratedClasses();
public ExtendedIterator listUnionClasses();
public ExtendedIterator listComplementClasses();
public ExtendedIterator listIntersectionClasses();
public ExtendedIterator listRestrictions();
public ExtendedIterator listNamedClasses();
public ExtendedIterator listHierarchyRootClasses();</pre>

    <p>The last two methods deserve special mention. In OWL, class expressions are typically
    not named, but are denoted by anonymous resources (aka <em>bNodes</em>). In many applications,
    such as displaying an ontology in a user interface, we want to pick out the named classes
    only, ignoring those denoted by bNodes. This is what <code>listNamedClasses()</code> does.
    The method <code>listHierarchyRootClasses()</code> identifies the classes that are uppermost
    in the class hierarchy contained in the given model. These are the classes that have no
    super-classes. The iteration returned by  <code>listHierarchyRootClasses()</code> <strong>may</strong>
    contain anonymous classes. To get a list of named hierarchy root classes, i.e. the named
    classes that lie closest to the top of the hierarchy (alternatively: the shallowest fringe
    of the hierarchy consisting solely of named classes), use the
    <a href="../javadoc/com/hp/hpl/jena/ontology/OntTools.html">OntTools</a>
    method <code>namedHierarchyRoots()</code>.</p>
    <p>You should also note that it is important to close the iterators returned from the <code>list&#133;</code>
    methods, particularly when the underlying store is a database. This is necessary so that any
    state (e.g. the database connection resources) can be released. Closing happens automatically
    when the <code>hasNext()</code> method on the iterator returns false. If your code does
    not iterate all the way to the end of the iterator, you should call the <code>close()</code> method
    explicitly. Note also that the values returned by these iterators will depend on the
    asserted data and the reasoner being used. For example, if the model contains a
    <code>Restriction</code>,
    that restriction will only be returned by the listClasses() iterator if the model is bound to
    a reasoner that can infer that any restriction is also be a class,
    since <code>Restriction</code> is a subClassOf <code>Class</code>.
    This difference can be exploited by the programmer: to list
    classes and restrictions separately, perform the <code>listClasses()</code> and
    <code>listRestictions()</code> methods on the base model only, or on a model with no reasoner attached.
    </p>

    <h2 id="instances">Instances or individuals</h2>

    <p> In OWL Full (and in DAML+OIL) any value can be an individual &#150; and thus the
      subject of triples in the RDF graph other than ontology declarations.
      In OWL Lite and DL, the language terms and the instance data that the application
      is working with are kept separate, by definition of the language.
      Jena therefore
      supports a simple notion of an <a href="../javadoc/com/hp/hpl/jena/ontology/Individual.html"><code>Individual</code></a>,
      which is essentially an alias for <code>Resource</code>. While <code>Individual</code>s
      are largely synonymous with <code>Resource</code>s, they do provide an programming interface
      that is consistent with the other Java classes in the ontology API.
    </p>
    <p>There are two ways to create individuals.
      Both requires the class to which the individual will initially belong:
    </p>
<pre class="codesample">OntClass c = m.createClass( NS + &quot;SomeClass&quot; );

// first way: use a call on OntModel
Individual ind0 = m.createIndividual( NS + &quot;ind0&quot;, c );

// second way: use a call on OntClass
Individual ind1 = c.createIndividual( NS + &quot;ind1&quot; );</pre>
    <p>
    The only real difference between these approaches is that the second way will create the
    individual in the same model that the class is attached to (see the <code>getModel()</code>
    method).
    In both of the above examples the individual is named, but this is
    not necessary. The method <code>OntModel.createIndividual(&nbsp;Resource cls&nbsp;)</code>
    creates an anonymous individual belonging to the given class. Note that the type of
    the class parameter is only <code>Resource</code>. You are not required to use <code>as()</code>
    to present a <code>Resource</code> to an <code>OntClass</code> before calling this method,
    though of course an <code>OntClass</code> is a <code>Resource</code> so using an
    <code>OntClass</code> will work perfectly well.</p>

    <p><code>Individual</code> provides a set of methods for testing and manipulating the
    ontology classes to which an individual belongs. This is a convenience: OWL and RDFS denote
    class membership through the <code>rdf:type</code> property, and methods for manipulating
    and testing <code>rdf:type</code> are defined on <code>OntResource</code>. You may use
    either approach interchangeably.</p>

    <h2 id="metadata">Ontology meta-data</h2>

    <p>In OWL and DAML+OIL, but not RDFS, meta-data about the ontology itself is
    encoded as properties on an individual of class <code>owl:Ontology</code>
    or <code>daml:Ontology</code> as appropriate. By convention, the URI of
    this individual is the URI of the ontology document itself. In the XML
    serialisation, this is typically shown as:</p>

<pre class="codesample">&lt;owl:Ontology rdf:about=&quot;&quot;&gt;
&lt;/owl:Ontology&gt;</pre>

    <p>Note that the construct <code>rdf:about=&quot;&quot;</code> does <em>not</em>
      indicate a resource with no URI; it is in fact a shorthand way of referencing
      the <em>base URI</em> of the document containing the ontology. The base URI
      may be stated in the document through an <code>xml:base</code> declaration
      in the XML preamble. The base URI can also be specified when reading the document via
      Jena's Model API (see the <code>read()</code> methods on
      <a href="../javadoc/com/hp/hpl/jena/ontology/OntModel.html"><code>OntModel</code></a>
      for reference).</p>

    <p>You can attach various meta-data statements to this object to indicate
      attributes of the ontology as a whole. The Java object <code>Ontology</code> represents this
      special instance, and uses the standard add, set, get, list, test and delete
      pattern to provide access to the following attributes: </p>

    <table class="definitions" summary="Ontology meta-data properties">
      <tr>
        <th class="def1a">Attribute</th><th class="def1b">Meaning</th>
      </tr>
      <tr>
        <td>backwardCompatibleWith</td>
        <td>
            Names a prior version of this ontology that this version is compatible with.
        </td>
      </tr>
      <tr>
        <td>incompatibleWith</td>
        <td>
            Names a prior version of this ontology that this version is not compatible with
        </td>
      </tr>
      <tr>
        <td>priorVersion</td>
        <td>
            Names a prior version of this ontology.
        </td>
      </tr>
      <tr>
        <td>imports</td>
        <td>
            Names an ontology whose definitions this ontology includes
        </td>
      </tr>
    </table>
    <p>In addition to these attributes, the Ontology element typically
    contains common meta-data properties, such as comment, label and version
    information.</p>
    <p>In the Jena API, the ontology's metadata properties can be accessed through
      the
      <a href="../javadoc/com/hp/hpl/jena/ontology/Ontology.html"><code>Ontology</code></a>
      interface.  Suppose I wish to know the list of URI's that the ontology imports.
      First I must obtain the resource representing the ontology itself:
    </p>
<pre class="codesample">String base = &#133;; // the base URI of the ontology
OntModel m = &#133;;  // the model containing the ontology statements
Ontology ont = m.getOntology( base );

// now list the ontology imports
for (Iterator i = ont.listImports(); i.hasNext(); ) {
    System.out.println( &quot;Ontology &quot; + base + &quot; imports &quot; + i.next() );
}</pre>

    <p>If the base URI of the ontology is not known, you can list all resources of <code>rdf:type</code>
    <code>Ontology</code> in a given model by <code>OntModel.listOntologies()</code>.
    If there is only one of these, it should be safe to assume that it is <em>the</em> Ontology
    resource for the ontology. However, you should note that if more than one ontology document
    has been read in to the model (for example by including the imports of a document), there may
    well be more than one <code>Ontology</code> resource in the model. In this
    case, you may find it useful to list the ontology resources in just the base model:
    </p>

<pre class="codesample">OntModel m = &#133; // the model, including imports
OntModel mBase = ModelFactory.createOntologyModel(
                      OntModelSpec.OWL_MEM, m.getBaseModel() );

for (Iterator i = mBase.listOntologies(); i.hasNext(); ) {
    Ontology ont = (Ontology) i.next();
    // m's base model has ont as an import ...
}
</pre>

    <p>
      A common practice is also to use the Ontology element to attach Dublin Core
      metadata to the ontology document. Jena provides a copy of the Dublin Core
      vocabulary, in <code>com.hp.hpl.jena.vocabulary.DC</code>. To attach a statement saying
      that the ontology was authored by John Smith, we can say:
    </p>
<pre class="codesample">Ontology ont = m.getOntology( baseURI );
ont.addProperty( DC.creator, &quot;John Smith&quot; );</pre>

    <p>It is also possible to programatically add imports and other meta-data to a
    model, for example:</p>

<pre class="codesample">String base = &#133;; // the base URI of the ontology
OntModel m = &#133;;

Ontology ont = m.createOntology( base );
ont.addImport( m.createResource( &quot;http://example.com/import1&quot; ) );
ont.addImport( m.createResource( &quot;http://example.com/import2&quot; ) );</pre>

    <p>Note that under default conditions, simply adding (or removing) an <code>owl:imports</code>
    statement to a model will not cause the corresponding document to be imported (or removed).
    However, by calling <code>OntModel.setDynamicImports(true)</code>, the model will start
    noticing the addition or removal of <code>owl:imports</code> statements.</p>

    <h2 id="inferenceIntro"> Ontology inference: overview</h2>

    <p>You have the choice of whether to use the Ontology API with Jena's
      reasoning capability turned on, and, if so, which of the various reasoners
      to use.
      Sometimes a reasoner will add information to the ontology model
      that it is not useful for your application to see. A good example is an ontology
      editor. Here, you may wish to present your users with the information
      they have entered in to their ontology; the addition of the entailed information
      into the editor's display would be very confusing. Since Jena does not
      have a means for distinguishing inferred statements from those statements asserted
      into the base model, a common choice for ontology editors and similar
      applications is to run with no reasoner.</p>
    <p>In many other cases, however, it is the addition of the reasoner that makes
      the ontology useful. For example, if we know that John is the father of Mary,
      we would expect a 'yes' if we query whether John is the parent of Mary. The parent
      relationship is not asserted, but we know from our ontology that <code>fatherOf</code>
      is a sub-property of <code>parentOf</code>. If 'John fatherOf Mary' is true,
      then 'John parentOf Mary' is also true. The integrated reasoning capability
      in Jena exists to allow just such entailments to be seen and used.
      </p>
    <p>For a complete and thorough description of Jena's inference capabilities, please
      see the <a href="../inference/index.html">reasoner documentation</a>. This section
      of of the ontology API documentation is intended to serve as only a brief guide
      and overview.</p>
    <p>Recall from the introduction that the reasoners in Jena operate by making it appear
    that triples <em>entailed</em> by the inference algorithm are part of the model in just
    the same way as the asserted triples (see Figure 2). The underlying architecture allows
    the reasoner to be part of the same Java virtual machine (as is the case with the built-in
    rule-based reasoners), or in a separate process on the local computer, or even a remote
    machine. Of course, each of these choices will have different characteristics of what
    reasoning capabilities are supported, and what the implications for performance are.</p>

    <p>The reasoner attached to an ontology model, if any, is specified through the
    <a href="../javadoc/com/hp/hpl/jena/ontology/OntModelSpec.html"><code>OntModelSpec</code></a>.
      The methods <code>setReasoner()</code> and <code>setReasonerFactory()</code>
      on the model spec are
      used to specify a reasoner. The setReasoner variant is intended for use on a
      specification which will only be used to build a single model. The factory variant
      is used where the <code>OntModelSpec</code> will be used to build more than one model, ensuring
      that each model gets its own reasoner object. The <code>ReasonerRegistry</code> provides
      a collection of pre-built reasoners &#150; see the reasoner documentation for more
      details. However, it is also possible for you to define your own
      reasoner that conforms to the appropriate interface. For example, there is
      an in-process interface to the open-source <a href="http://pellet.owldl.com/">Pellet reasoner</a>.</p>

    <p>To facilitate the choice of reasoners for a given model, some common choices
      have been included in the pre-built ontology model specifications available
      as static fields on <code>OntModelSpec</code>. The available choices are
      described in the section on <a href="#ontModelSpecs">ont model specifications</a>, above.
      </p>
    <p>Depending on which of these choices is made, the statements returned from queries
      to a given ontology model may vary considerably.</p>
        <h3>Additional notes</h3>
    <p>Jena's inference machinery defines some specialised services that are not exposed
      through the addition of extra triples to the model. These are exposed by the
      <a href="../javadoc/com/hp/hpl/jena/rdf/model/InfModel.html"><code>InfModel</code></a>
      interface; for convenience OntModel extends this interface to make these services
      directly available to the user. Please note that calling inference-specific
      methods on an ontology model that does not contain a reasoner will have unpredictable
      results. Typically these methods will have no effect or return null, but you
      should not rely on this behaviour.</p>
    <p>In general, inference models will add a lot of additional statements to a given
      model, including the axioms appropriate to the ontology language. This is typically
      not something you will want in the output when the model is serialized, so <em><code>write()</code>
      on an ontology model <strong>will only write the statements from the base model</strong>.</em>
      This is typically the desired behaviour, but there are occasions (e.g. during
      debugging) when you may want to write the entire model, virtual triples included.
      The easiest way to achieve this is to call the <code>writeAll()</code> method
      on <code>OntModel</code>. An alternative technique, which can sometimes be useful
      for a variety of use-cases, including debugging, is to snapshot the model by
      constructing a temporary plain model and adding to it:
      the contents of the ontology model:</p>
<pre class="codesample">OntModel m = &#133;

// snapshot the contents of ont model om
Model snapshot = ModelFactory.createDefaultModel();
snapshot.add( om );</pre>
    <p>See also the note on <a href="common-problems.html#aBox-tBox">combining a-box and t-box
      data</a> using the OntModel.</p>

    <h2 id="legacyDAML">Working with DAML+OIL ontologies</h2>
    <p><strong>Jena 2.5 update</strong> With effect from release 2.5 of Jena,
    the legacy DAML+OIL API was deprecated, and has been removed
    from the 2.6 release. The effect of this is
    that users of DAML+OIL using the legacy API (i.e. the classes in
    <code>com.hp.hpl.jena.ontology.daml</code>) should move their projects
    either to work with OWL, or at least to work with the DAML+OIL profile
    of the standard <code>OntModel</code>. The DAML+OIL <code>OntModel</code>
    profile will continue to be supported.
    </p>
    <p>Generally speaking, we recommend that developers who want to work on Semantic
      Web applications should use RDFS or <a href="http://www.w3.org/2004/OWL/">OWL</a>,
      as their ontology language. OWL has had the benefit of a more rigorous design
      and significant input to its design from researchers with insights into the design
      of efficient reasoning algorithms. Nevertheless, there remains some legacy
      ontology data on the Semantic Web today encoded in <a href="http://www.daml.org">DAML+OIL</a>,
      the precursor to OWL. Jena 2 currently supports ontology processing in
      DAML+OIL as well as OWL and RDFS. However, DAML reasoning using the built-in
      Jena reasoners is more restricted than is the case with OWL.</p>
    <p>Since Jena 2.6, the ontology API (as described in this document) is the
      only available route for processing DAML data. Using the language profile, the
      ontology API can handle RDFS, OWL and DAML sources with equal ease. Thus, OntClass
      can be used to represent a DAML class, an OWL class or an RDFS class.</p>

    <h2 id="persistence">Working with persistent ontologies</h2>

    <p>A common way to work with ontology data is to load the ontology
      axioms and instances at run-time from a set of source documents. This is a very
      flexible approach, but has limitations. In particular, your application must
      parse the source documents
      each time it is run. For large ontologies, this can
      be a source of significant overhead. Jena provides an implementation of the
      RDF model interface that stores the triples persistently in a database. This
      saves the overhead of loading the model each time, and means that you can store
      RDF models
      significantly larger than the computer's main memory, but at the
      expense of a higher overhead (a database interaction) to retrieve and update
      RDF data from the model. In this section I show how to use the ontology API with
      Jena's persistent database models.</p>

    <p>For information on setting-up and accessing the database models
      themselves, see the <a href="../DB/index.html">DB documentation</a>. I do not
      cover this aspect in this section. For a method of using a persistent
      database to manage ontology imports, see
      <a href="http://www.iandickinson.me.uk/articles/jena-tip-db-import/">this article</a>.</p>

    <p>There are two somewhat separate requirements for persistently
      storing ontology data. The first is making the main or base model itself persistent.
      The second is re-using or creating persistent models for the imports of an ontology.
      These two requirements are handled slightly differently. A simple, but complete,
      example of using persistent database models for storing ontologies
      <a href="../examples/persistent-ont-model/index.html">is included with Jena</a>.</p>

    <p>To retrieve a Jena model from the database API, we have to know its name.
      Fortunately, common practice for ontologies on the Semantic Web is that each
      is named with a URI. We use this URI to name the model that is stored in the
      database. Note carefully what is actually happening here: we are exploiting
      a feature of the database sub-system to make persistently stored ontologies
      easy to retrieve, but we are not in any sense resolving the URI of the model.
      Once placed into the database, the name of the model is treated as an opaque
      string.</p>
    <p>To create a persistent model for the ontology <code>http://example.org/Customers</code>,
      we create a model maker that will access our underlying database, and use the
      ontology URI as the database name. We then take the resulting persistent model,
      and use it as the base model when constructing an ontology model:</p>
<pre class="codesample">Model base = getMaker().createModel( &quot;http://example.org/Customers&quot; );
OntModel m = ModelFactory.createOntologyModel( OntModelSpec.OWL_MEM_RULE_INF, base );</pre>

    <p>Here we assume that the <code>getMaker()</code> method returns a suitably initialized<code>ModelMaker</code>
      that will open the connection to the database. This step only creates a persistent
      model named with the ontology URI. To initialise the content, we must either
      add statements to the model using the OntModel API, or do a one-time read from
      a document:</p>
<pre class="codesample">m.read( &quot;http://example.org/Customers&quot; );</pre>
    <p>Once this step is completed, the model contents may be accessed in future without
      needing to read again.</p>
    <p>If the Customers ontology imports other ontologies, using <code>owl:imports</code> or <code>daml:imports</code>,
      the Jena Ontology API will build a union model containing the closure of the
      imports. Even if the base model is persistent, the predefined <code>OntModelSpec</code> objects
      only specify memory models to contain the imported ontologies, since memory
      models do not require any additional parameters.</p>
    <p>To specify that the imported models should stored in, and retrieved from, the
      database, we must update the ontology spec object to use the model maker that
      encapsulates the database connection:</p>
<pre class="codesample">OntModelSpec spec = new OntModelSpec( OntModelSpec.OWL_MEM_RULE_INF );
// set the model maker for the base model
spec.setBaseModelMaker( getMaker() );
// set the model maker for imports
spec.setImportModelMaker( getMaker() );</pre>

    <p>This new model maker will then be used to generate persistent models named
      with the URI of the imported ontology, if it passed instead of OntModelSpec.OWL_MEM_RULE_INF
      to the createOntologyModel method of the model factory. Note that once the import
      has been loaded once into the database, it can be re-used by other ontologies
      that import it. Thus a given database will only contain at most one copy of
      each imported ontology.</p>
    <p><strong>Note on performance</strong> The built-in Jena reasoners, including the rule
    reasoners, make many small queries into the model in order to propagate the effects
    of rules firing. When using a persistent database model, each of these small queries
    creates an SQL interaction with the database engine. This is a very inefficient way to
    interact with a database system, and performance suffers as a result. Efficient reasoning
    over large, persistent databases is currently an open research challenge. Our best
    suggested work-around is, where possible, to snapshot the contents of the database-backed
    model into RAM for the duration of processing by the inference engine. An alternative
    solution, that may be applicable if your application does not write to the datastore often,
    is to precompute the inference closure of the ontology and data in-memory, then store that
    into a database model to be queried by the run-time application. Such an off-line processing
    architecture will clearly not be applicable to every application problem.</p>
    <p>A <a href="../examples/persistent-ont-model/index.html">sample program</a> shows
      the above steps combined, to create an ontology in which both base model
      and imports are stored in a persistent database.</p>

    <h2 id="ontTools">Experimental ontology tools</h2>
    <p>Starting with Jena release  2.6, the <code>OntTools</code> class provides a small collection
    of commonly-requested utilities for assisting with ontology processing. Given that this is a new
    feature, you should regard it as an experimental facility for the time being. We welcome feedback.
    The capabilities in <code>OntTools</code> are implemented as static methods. Currently available
    tools are:</p>
    <ul>
      <li><code>OntClass getLCA( OntModel m, OntClass u, OntClass v )</code><br />
      Determine the <em>lowest common ancestor</em> for classes u and v. This is the class that
      is lowest in the class hierarchy, and which includes both u and v among its sub-classes.</li>
      <li><code>Path findShortestPath( Model m, Resource start, RDFNode end, Filter onPath )</code><br />
      Breadth-first search, including a cycle check, to locate the shortest path from <code>start</code>
      to <code>end</code>, in which every triple on the path returns <code>true</code> to
      the <code>onPath</code> predicate.</li>
      <li><code>List namedHierarchyRoots( OntModel m ) </code><br />
      Compute a list containing the uppermost fringe of the class hierarchy in the given model which
      consists only of named classes.</li>
    </ul>
    <p class="footnote" style="font-style:italic;margin-top:3em;padding-top:1em">Author: Ian Dickinson<br />
    Last modified: $Id: index.html,v 1.32 2009/02/24 15:15:20 ian_dickinson Exp $
</body>
</html>
